OpenSearchEngine Class Reference

A class representing a single search engine described in OpenSearch format. More...

#include <opensearchengine.h>

Inheritance diagram for OpenSearchEngine:

Public Types
using	Parameter = QPair< QString, QString >
using	Parameters = QList< Parameter >

Public Slots
void	requestSuggestions (const QString &searchTerm)
void	requestSearchResults (const QString &searchTerm)

Signals
void	imageChanged ()
void	suggestions (const QStringList &suggestions)

Public Member Functions
	OpenSearchEngine (QObject *parent=nullptr)
	~OpenSearchEngine ()
QString	name () const
void	setName (const QString &name)
QString	description () const
void	setDescription (const QString &description)
QString	searchUrlTemplate () const
void	setSearchUrlTemplate (const QString &searchUrl)
QUrl	searchUrl (const QString &searchTerm) const
QByteArray	getPostData (const QString &searchTerm) const
bool	providesSuggestions () const
QString	suggestionsUrlTemplate () const
void	setSuggestionsUrlTemplate (const QString &suggestionsUrl)
QUrl	suggestionsUrl (const QString &searchTerm) const
Parameters	searchParameters () const
void	setSearchParameters (const Parameters &searchParameters)
Parameters	suggestionsParameters () const
void	setSuggestionsParameters (const Parameters &suggestionsParameters)
QString	searchMethod () const
void	setSearchMethod (const QString &method)
QString	suggestionsMethod () const
void	setSuggestionsMethod (const QString &method)
QString	imageUrl () const
void	setImageUrl (const QString &url)
QImage	image () const
void	setImage (const QImage &image)
bool	isValid () const
void	setSuggestionsUrl (const QString &string)
void	setSuggestionsParameters (const QByteArray &parameters)
QString	getSuggestionsUrl ()
QByteArray	getSuggestionsParameters ()
QNetworkAccessManager *	networkAccessManager () const
void	setNetworkAccessManager (QNetworkAccessManager *networkAccessManager)
OpenSearchEngineDelegate *	delegate () const
void	setDelegate (OpenSearchEngineDelegate *delegate)
bool	operator== (const OpenSearchEngine &other) const
bool	operator< (const OpenSearchEngine &other) const

Protected Member Functions
void	loadImage () const

Static Protected Member Functions
static QString	parseTemplate (const QString &searchTerm, const QString &searchTemplate)

Properties
QString	name
	the name of the engine More...
QString	description
	the description of the engine More...
QString	searchUrlTemplate
	the template of the search URL More...
Parameters	searchParameters
QString	searchMethod
QString	suggestionsUrlTemplate
	the template of the suggestions URL More...
Parameters	suggestionsParameters
QString	suggestionsMethod
bool	providesSuggestions
QString	imageUrl
bool	valid
QNetworkAccessManager *	networkAccessManager

Detailed Description

A class representing a single search engine described in OpenSearch format.

OpenSearchEngine is a class that represents a single search engine based on the OpenSearch format. For more information about the format, see http://www.opensearch.org/.

Instances of the class hold all the data associated with the corresponding search engines, such as name(), description() and also URL templates that are used to construct URLs, which can be used later to perform search queries. Search engine can also have an image, even an external one, in this case it will be downloaded automatically from the network.

OpenSearchEngine instances can be constructed from scratch but also read from external sources and written back to them. OpenSearchReader and OpenSearchWriter are the classes provided for reading and writing OpenSearch descriptions.

Default constructed engines need to be filled with the necessary information before they can be used to perform search requests. First of all, a search engine should have the metadata including the name and the description. However, the most important are URL templates, which are the construction of URLs but can also contain template parameters, that are replaced with corresponding values at the time of constructing URLs.

There are two types of URL templates: search URL template and suggestions URL template. Search URL template is needed for constructing search URLs, which point directly to search results. Suggestions URL template is necessary to construct suggestion queries URLs, which are then used for requesting contextual suggestions, a popular service offered along with search results that provides search terms related to what has been supplied by the user.

Both types of URLs are constructed by the class, by searchUrl() and suggestionsUrl() functions respectively. However, search requests are supposed to be performed outside the class, while suggestion queries can be executed using the requestSuggestions() method. The class will take care of performing the network request and parsing the JSON response.

Both the image request and suggestion queries need network access. The class can perform network requests on its own, though the client application needs to provide a network access manager, which then will to be used for network operations. Without that, both images delivered from remote locations and contextual suggestions will be disabled.

See also

OpenSearchReader, OpenSearchWriter

Definition at line 52 of file opensearchengine.h.

Member Typedef Documentation

Parameter

using OpenSearchEngine::Parameter = QPair<QString, QString>

Definition at line 61 of file opensearchengine.h.

Parameters

using OpenSearchEngine::Parameters = QList<Parameter>

Definition at line 62 of file opensearchengine.h.

Constructor & Destructor Documentation

OpenSearchEngine()

OpenSearchEngine::OpenSearchEngine

(

QObject *

parent = nullptr

)

Constructs an engine with a given parent.

Definition at line 102 of file opensearchengine.cpp.

~OpenSearchEngine()

OpenSearchEngine::~OpenSearchEngine ( )

default

A destructor.

Member Function Documentation

delegate()

OpenSearchEngineDelegate * OpenSearchEngine::delegate

(

)

const

Definition at line 678 of file opensearchengine.cpp.

description()

QString OpenSearchEngine::description

(

)

const

Definition at line 161 of file opensearchengine.cpp.

getPostData()

QByteArray OpenSearchEngine::getPostData

(

const QString &

searchTerm

)

const

Definition at line 242 of file opensearchengine.cpp.

getSuggestionsParameters()

QByteArray OpenSearchEngine::getSuggestionsParameters

(

)

Definition at line 536 of file opensearchengine.cpp.

getSuggestionsUrl()

QString OpenSearchEngine::getSuggestionsUrl

(

)

Definition at line 531 of file opensearchengine.cpp.

image()

QImage OpenSearchEngine::image

(

)

const

Definition at line 462 of file opensearchengine.cpp.

imageChanged

void OpenSearchEngine::imageChanged ( )

signal

This signal is emitted whenever the image of the engine changes.

See also

image(), imageUrl()

imageUrl()

QString OpenSearchEngine::imageUrl

(

)

const

Definition at line 412 of file opensearchengine.cpp.

isValid()

bool OpenSearchEngine::isValid

(

)

const

Definition at line 489 of file opensearchengine.cpp.

loadImage()

void OpenSearchEngine::loadImage ( ) const

protected

Definition at line 422 of file opensearchengine.cpp.

name()

QString OpenSearchEngine::name

(

)

const

Definition at line 145 of file opensearchengine.cpp.

networkAccessManager()

QNetworkAccessManager * OpenSearchEngine::networkAccessManager

(

)

const

Definition at line 661 of file opensearchengine.cpp.

operator<()

bool OpenSearchEngine::operator<

(

const OpenSearchEngine &

other

)

const

Definition at line 505 of file opensearchengine.cpp.

operator==()

bool OpenSearchEngine::operator==

(

const OpenSearchEngine &

other

)

const

Definition at line 494 of file opensearchengine.cpp.

parseTemplate()

QString OpenSearchEngine::parseTemplate ( const QString &  searchTerm, const QString &  searchTemplate  )

staticprotected

Definition at line 120 of file opensearchengine.cpp.

providesSuggestions()

bool OpenSearchEngine::providesSuggestions

(

)

const

Definition at line 266 of file opensearchengine.cpp.

requestSearchResults

void OpenSearchEngine::requestSearchResults ( const QString &  searchTerm )

slot

Requests search results on the search engine, for a given searchTerm.

The default implementation does nothing, to supply your own you need to create your own OpenSearchEngineDelegate subclass and supply it to the engine. Then the function will call the performSearchRequest() method of the delegate, which can then handle the request in a custom way.

See also

requestSuggestions(), delegate()

Definition at line 598 of file opensearchengine.cpp.

requestSuggestions

void OpenSearchEngine::requestSuggestions ( const QString &  searchTerm )

slot

Definition at line 550 of file opensearchengine.cpp.

searchMethod()

QString OpenSearchEngine::searchMethod

(

)

const

Definition at line 366 of file opensearchengine.cpp.

searchParameters()

OpenSearchEngine::Parameters OpenSearchEngine::searchParameters

(

)

const

Definition at line 335 of file opensearchengine.cpp.

searchUrl()

QUrl OpenSearchEngine::searchUrl

(

const QString &

searchTerm

)

const

Constructs and returns a search URL with a given searchTerm.

The URL template is processed according to the specification: http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_URL_template_syntax

A list of template parameters currently supported and what they are replaced with: \table \header \o parameter \o value \row \o "{count}" \o "20" \row \o "{startIndex}" \o "0" \row \o "{startPage}" \o "0" \row \o "{language}" \o "the default language code (RFC 3066)" \row \o "{inputEncoding}" \o "UTF-8" \row \o "{outputEncoding}" \o "UTF-8" \row \o "{*:source}" \o "application name, QCoreApplication::applicationName()" \row \o "{searchTerms}" \o "the string supplied by the user" \endtable

See also

searchUrlTemplate(), searchParameters(), suggestionsUrl()

Definition at line 221 of file opensearchengine.cpp.

searchUrlTemplate()

QString OpenSearchEngine::searchUrlTemplate

(

)

const

Definition at line 177 of file opensearchengine.cpp.

setDelegate()

void OpenSearchEngine::setDelegate

(

OpenSearchEngineDelegate *

delegate

)

Definition at line 683 of file opensearchengine.cpp.

setDescription()

void OpenSearchEngine::setDescription

(

const QString &

description

)

Definition at line 166 of file opensearchengine.cpp.

setImage()

void OpenSearchEngine::setImage

(

const QImage &

image

)

Definition at line 470 of file opensearchengine.cpp.

setImageUrl()

void OpenSearchEngine::setImageUrl

(

const QString &

url

)

Definition at line 417 of file opensearchengine.cpp.

setName()

void OpenSearchEngine::setName

(

const QString &

name

)

Definition at line 150 of file opensearchengine.cpp.

setNetworkAccessManager()

void OpenSearchEngine::setNetworkAccessManager

(

QNetworkAccessManager *

networkAccessManager

)

Definition at line 666 of file opensearchengine.cpp.

setSearchMethod()

void OpenSearchEngine::setSearchMethod

(

const QString &

method

)

Definition at line 371 of file opensearchengine.cpp.

setSearchParameters()

void OpenSearchEngine::setSearchParameters

(

const Parameters &

searchParameters

)

Definition at line 340 of file opensearchengine.cpp.

setSearchUrlTemplate()

void OpenSearchEngine::setSearchUrlTemplate

(

const QString &

searchUrl

)

Definition at line 182 of file opensearchengine.cpp.

setSuggestionsMethod()

void OpenSearchEngine::setSuggestionsMethod

(

const QString &

method

)

Definition at line 390 of file opensearchengine.cpp.

setSuggestionsParameters() [1/2]

void OpenSearchEngine::setSuggestionsParameters

(

const Parameters &

suggestionsParameters

)

Definition at line 357 of file opensearchengine.cpp.

setSuggestionsParameters() [2/2]

void OpenSearchEngine::setSuggestionsParameters

(

const QByteArray &

parameters

)

Requests contextual suggestions on the search engine, for a given searchTerm.

If succeeded, suggestions() signal will be emitted once the suggestions are received.

Note

To be able to request suggestions, you need to provide a network access manager, which will be used for network operations.

See also

requestSearchResults()

Definition at line 521 of file opensearchengine.cpp.

setSuggestionsUrl()

void OpenSearchEngine::setSuggestionsUrl

(

const QString &

string

)

Definition at line 526 of file opensearchengine.cpp.

setSuggestionsUrlTemplate()

void OpenSearchEngine::setSuggestionsUrlTemplate

(

const QString &

suggestionsUrl

)

Definition at line 282 of file opensearchengine.cpp.

suggestions

void OpenSearchEngine::suggestions ( const QStringList &  suggestions )

signal

This signal is emitted whenever new contextual suggestions have been provided by the search engine. To request suggestions, use requestSuggestions(). The suggestion set is specified by suggestions.

See also

requestSuggestions()

suggestionsMethod()

QString OpenSearchEngine::suggestionsMethod

(

)

const

Definition at line 385 of file opensearchengine.cpp.

suggestionsParameters()

OpenSearchEngine::Parameters OpenSearchEngine::suggestionsParameters

(

)

const

Definition at line 352 of file opensearchengine.cpp.

suggestionsUrl()

QUrl OpenSearchEngine::suggestionsUrl

(

const QString &

searchTerm

)

const

Constructs a suggestions URL with a given searchTerm.

The URL template is processed according to the specification: http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_URL_template_syntax

See searchUrl() for more information about processing template parameters.

See also

suggestionsUrlTemplate(), suggestionsParameters(), searchUrl()

Definition at line 301 of file opensearchengine.cpp.

suggestionsUrlTemplate()

QString OpenSearchEngine::suggestionsUrlTemplate

(

)

const

Definition at line 277 of file opensearchengine.cpp.

Property Documentation

description

OpenSearchEngine::description

readwrite

the description of the engine

See also

name()

Definition at line 58 of file opensearchengine.h.

imageUrl

QString OpenSearchEngine::imageUrl

readwrite

Definition at line 58 of file opensearchengine.h.

name

OpenSearchEngine::name

readwrite

the name of the engine

See also

description()

Definition at line 58 of file opensearchengine.h.

networkAccessManager

QNetworkAccessManager* OpenSearchEngine::networkAccessManager

readwrite

Definition at line 58 of file opensearchengine.h.

providesSuggestions

bool OpenSearchEngine::providesSuggestions

read

Definition at line 58 of file opensearchengine.h.

searchMethod

QString OpenSearchEngine::searchMethod

readwrite

Definition at line 58 of file opensearchengine.h.

searchParameters

Parameters OpenSearchEngine::searchParameters

readwrite

Definition at line 58 of file opensearchengine.h.

searchUrlTemplate

OpenSearchEngine::searchUrlTemplate

readwrite

the template of the search URL

See also

searchUrl(), searchParameters(), suggestionsUrlTemplate()

Definition at line 58 of file opensearchengine.h.

suggestionsMethod

QString OpenSearchEngine::suggestionsMethod

readwrite

Definition at line 58 of file opensearchengine.h.

suggestionsParameters

Parameters OpenSearchEngine::suggestionsParameters

readwrite

Definition at line 58 of file opensearchengine.h.

suggestionsUrlTemplate

OpenSearchEngine::suggestionsUrlTemplate

readwrite

the template of the suggestions URL

See also

suggestionsUrl(), suggestionsParameters(), searchUrlTemplate()

Definition at line 58 of file opensearchengine.h.

valid

bool OpenSearchEngine::valid

read

Definition at line 58 of file opensearchengine.h.

---

The documentation for this class was generated from the following files:

• src/lib/opensearch/opensearchengine.h
• src/lib/opensearch/opensearchengine.cpp