HydroCoupleOgc  0.1.0
OGC web service clients (WMS, WMTS, WCS, WFS) over Qt Network (0.1.0)
Loading...
Searching...
No Matches
HydroCouple::Ogc Namespace Reference

Classes

struct  CrsIdentifier
 An authority and the code it assigns, e.g. EPSG and 3857. More...
 
class  HttpClient
 One network access manager, shared, with the bookkeeping around it that a tiled map needs. More...
 
struct  HttpResponse
 What came back. More...
 
struct  WcsCapabilities
 What a WCS server said about itself. More...
 
struct  WcsCoverageDescription
 What DescribeCoverage says one coverage actually is. More...
 
struct  WcsCoverageSummary
 One coverage as the capabilities document lists it. More...
 
struct  WcsGetCoverageRequest
 What to ask a WCS for. More...
 
struct  WcsRangeField
 One band, or field, of a coverage's range. More...
 
struct  WfsCapabilities
 What a WFS server said about itself. More...
 
struct  WfsFeatureType
 One collection of features a WFS publishes. More...
 
struct  WfsGetFeatureRequest
 One GetFeature. More...
 
struct  WmsCapabilities
 What a WMS server said about itself. More...
 
struct  WmsGetMapRequest
 One GetMap. More...
 
struct  WmsLayerInfo
 One layer a WMS offers. More...
 
struct  WmtsCapabilities
 What a WMTS server said about itself. More...
 
struct  WmtsLayerInfo
 One layer a WMTS offers. More...
 
struct  WmtsResourceTemplate
 A URL template the server publishes for fetching tiles directly. More...
 
struct  WmtsTileMatrix
 One level of a tile pyramid. More...
 
struct  WmtsTileMatrixSet
 A pyramid, and the system it is laid out in. More...
 

Enumerations

enum class  ServiceKind {
  Unknown ,
  Wms ,
  Wmts ,
  Wfs ,
  Wcs
}
 The kinds of service this library speaks. More...
 

Functions

HYDROCOUPLEOGC_EXPORT bool authorityWritesLatitudeFirst (const QString &crs)
 Whether the authority defines crs latitude first.
 
HYDROCOUPLEOGC_EXPORT CrsIdentifier parseCrsIdentifier (const QString &text)
 Reads any of the spellings OGC services use for a system.
 
HYDROCOUPLEOGC_EXPORT Q_DECLARE_LOGGING_CATEGORY (ogcHttp) struct HYDROCOUPLEOGC_EXPORT ServiceCredentials
 Everything this library logs, off unless asked for.
 
HYDROCOUPLEOGC_EXPORT QString redactedUrl (const QUrl &url)
 url with anything secret in it replaced.
 
HYDROCOUPLEOGC_EXPORT QString buildCapabilitiesUrl (const QString &serviceUrl, ServiceKind kind)
 Where to ask serviceUrl what it can do.
 
HYDROCOUPLEOGC_EXPORT ServiceKind detectServiceKind (const QByteArray &xml)
 What kind of service answered.
 
HYDROCOUPLEOGC_EXPORT WcsCapabilities parseWcsCapabilities (const QByteArray &xml)
 Reads a WCS GetCapabilities response.
 
HYDROCOUPLEOGC_EXPORT WcsCoverageDescription parseWcsCoverageDescription (const QByteArray &xml)
 Reads a WCS 2.0 DescribeCoverage response.
 
HYDROCOUPLEOGC_EXPORT QString wcsExceptionText (const QByteArray &body)
 What an OGC exception report says, if that is what this is.
 
HYDROCOUPLEOGC_EXPORT QString buildGetCoverageUrl (const QString &serviceUrl, const QString &version, const WcsGetCoverageRequest &request, const WcsCoverageDescription &description)
 Builds a GetCoverage URL.
 
HYDROCOUPLEOGC_EXPORT QString buildDescribeCoverageUrl (const QString &serviceUrl, const QString &version, const QString &coverageId)
 Builds a DescribeCoverage URL.
 
HYDROCOUPLEOGC_EXPORT QString nextWcsVersion (const QString &version)
 The next version to try after version was refused.
 
HYDROCOUPLEOGC_EXPORT WfsCapabilities parseWfsCapabilities (const QByteArray &xml)
 Reads a WFS GetCapabilities response.
 
HYDROCOUPLEOGC_EXPORT QString buildGetFeatureUrl (const WfsCapabilities &capabilities, const WfsGetFeatureRequest &request)
 Builds a GetFeature URL.
 
HYDROCOUPLEOGC_EXPORT QString preferredOutputFormat (const WfsFeatureType &type, const QStringList &serviceFormats)
 The best format to ask type for, of those it offers.
 
HYDROCOUPLEOGC_EXPORT bool isGeoJsonFormat (const QString &format)
 
HYDROCOUPLEOGC_EXPORT WmsCapabilities parseWmsCapabilities (const QByteArray &xml)
 Reads a WMS GetCapabilities response.
 
HYDROCOUPLEOGC_EXPORT QString buildGetMapUrl (const WmsCapabilities &capabilities, const WmsGetMapRequest &request)
 Builds a GetMap URL.
 
HYDROCOUPLEOGC_EXPORT bool wmsAxisOrderIsLatitudeFirst (const QString &crs, const QString &version)
 Whether crs is written latitude first under WMS version.
 
HYDROCOUPLEOGC_EXPORT WmtsCapabilities parseWmtsCapabilities (const QByteArray &xml)
 Reads a WMTS GetCapabilities response.
 
HYDROCOUPLEOGC_EXPORT QString buildWmtsTileUrl (const WmtsCapabilities &capabilities, const WmtsLayerInfo &layer, const QString &matrixSetId, const QString &matrixId, int row, int column, const QString &style=QString(), const QString &format=QString())
 Builds the URL for one tile.
 

Enumeration Type Documentation

◆ ServiceKind

enum class HydroCouple::Ogc::ServiceKind
strong

The kinds of service this library speaks.

Enumerator
Unknown 
Wms 
Wmts 
Wfs 
Wcs 

Function Documentation

◆ authorityWritesLatitudeFirst()

bool HydroCouple::Ogc::authorityWritesLatitudeFirst ( const QString & crs)
nodiscard

Whether the authority defines crs latitude first.

A short list rather than the register: these are the geographic systems a service in this application is actually asked for, and every projected system it uses — Web Mercator above all — is easting first. The hosts carry a coordinate database and can answer this properly; this exists so that the parsers, which carry none, are not left guessing.

Parameters
crsThe system, in any of the spellings services use.
Returns
Whether latitude is written first. False for anything not recognised, which is the safer wrong answer: it is the order every pre-1.3.0 service used and the order every projected system uses.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ buildCapabilitiesUrl()

QString HydroCouple::Ogc::buildCapabilitiesUrl ( const QString & serviceUrl,
ServiceKind kind )
nodiscard

Where to ask serviceUrl what it can do.

The address the user pasted usually already carries parameters — a MapServer mapfile, a workspace, a tenant — so they are kept and the request is added to them. Any GetCapabilities parameters already in it are replaced rather than duplicated: a URL copied out of a browser is as often a whole GetCapabilities request as it is a bare endpoint, and a query with two SERVICE parameters is answered by neither server the user might be talking to.

Parameters
serviceUrlThe address as the user gave it.
kindWhich dialect to ask in.
Returns
The URL to fetch, or empty when serviceUrl is not one.

◆ buildDescribeCoverageUrl()

QString HydroCouple::Ogc::buildDescribeCoverageUrl ( const QString & serviceUrl,
const QString & version,
const QString & coverageId )
nodiscard

Builds a DescribeCoverage URL.

◆ buildGetCoverageUrl()

QString HydroCouple::Ogc::buildGetCoverageUrl ( const QString & serviceUrl,
const QString & version,
const WcsGetCoverageRequest & request,
const WcsCoverageDescription & description )
nodiscard

Builds a GetCoverage URL.

Parameters
serviceUrlWhere the service lives.
versionThe protocol version to write, e.g. "2.0.1".
requestWhat is wanted.
descriptionThe coverage as DescribeCoverage gave it, whose axis labels a 2.0 request is written against. Ignored by the 1.x forms, which are positional.
Returns
The URL, or empty when the request cannot be written – notably a 2.0 request for a coverage whose axes are unknown or unrecognisable, which must be refused rather than guessed at: a subset naming an axis the coverage does not have is answered with an error status, and a caller that reads only the status will mistake it for a version it should retry.

◆ buildGetFeatureUrl()

QString HydroCouple::Ogc::buildGetFeatureUrl ( const WfsCapabilities & capabilities,
const WfsGetFeatureRequest & request )
nodiscard

Builds a GetFeature URL.

The spelling follows the version the document DECLARED, which differs more than WMS's does: 2.0.0 asks by TYPENAMES and limits by COUNT, while 1.1.0 and 1.0.0 ask by TYPENAME and limit by MAXFEATURES. A request in the wrong dialect is not refused — a server that does not recognise MAXFEATURES ignores it and returns everything it has.

A bounding box is written in the authority's axis order from 1.1.0 on, exactly as a WMS 1.3.0 one is, and 2.0.0 appends the system to the box so the server need not guess which order was meant.

Parameters
capabilitiesWhat the server published.
requestWhat to ask for.
Returns
The URL, or empty when the request cannot be built.
Here is the call graph for this function:

◆ buildGetMapUrl()

QString HydroCouple::Ogc::buildGetMapUrl ( const WmsCapabilities & capabilities,
const WmsGetMapRequest & request )
nodiscard

Builds a GetMap URL.

Two things follow from the document's declared version rather than from the version that was asked for:

  • the coordinate system is named SRS before 1.3.0 and CRS from 1.3.0 on;
  • from 1.3.0 on the bounding box is written in the authority's axis order, so a request in EPSG:4326 puts latitude first, while one in a projected system such as EPSG:3857 — or in CRS:84, which exists precisely to be longitude-first — does not. A client that swaps for every 1.3.0 request draws the world sideways; one that never swaps draws a geographic request somewhere else entirely.
Parameters
capabilitiesWhat the server published.
requestWhat to ask for.
Returns
The URL, or empty when the request cannot be built.
Here is the call graph for this function:

◆ buildWmtsTileUrl()

QString HydroCouple::Ogc::buildWmtsTileUrl ( const WmtsCapabilities & capabilities,
const WmtsLayerInfo & layer,
const QString & matrixSetId,
const QString & matrixId,
int row,
int column,
const QString & style = QString(),
const QString & format = QString() )
nodiscard

Builds the URL for one tile.

A published template is used when there is one, and a KVP query built only when there is not. Servers that offer both often serve the templates from a pool of hosts and the KVP endpoint from one, so preferring the template is not merely a matter of taste — and a client that only ever builds KVP cannot talk to a REST-only server at all.

Parameters
capabilitiesWhat the server published.
layerThe layer to fetch from.
matrixSetIdWhich pyramid.
matrixIdWhich level of it.
rowTile row.
columnTile column.
styleThe style, or empty for the layer's default.
formatThe image format, or empty for the layer's first.
Returns
The URL, or an empty string when the request cannot be built.

◆ detectServiceKind()

ServiceKind HydroCouple::Ogc::detectServiceKind ( const QByteArray & xml)
nodiscard

What kind of service answered.

Decided from the element names, so it costs nothing and works on a document this library could not otherwise parse. A WMS calls its root WMS_Capabilities, or WMT_MS_Capabilities before 1.3.0; a WFS calls its root WFS_Capabilities; a WMTS calls its root simply Capabilities — and may wrap it in a SOAP envelope, which is why the root alone is not what is looked at.

Parameters
xmlA capabilities response.
Returns
The kind, or Unknown for anything else — including an exception report, which is not an answer about a service.

◆ isGeoJsonFormat()

bool HydroCouple::Ogc::isGeoJsonFormat ( const QString & format)
nodiscard
Returns
Whether format is a GeoJSON one.
Here is the caller graph for this function:

◆ nextWcsVersion()

QString HydroCouple::Ogc::nextWcsVersion ( const QString & version)
nodiscard

The next version to try after version was refused.

Returns
The next one down, or empty when there is none left.

One ladder, deliberately. The port this came from had two identical copies – one for capabilities, one for GetCoverage – whose comment claimed they differed. What differs is which request gets retried, which is the caller's business, not the ladder's.

◆ parseCrsIdentifier()

CrsIdentifier HydroCouple::Ogc::parseCrsIdentifier ( const QString & text)
nodiscard

Reads any of the spellings OGC services use for a system.

Version segments are skipped wherever they appear: EPSG::3857, EPSG:6.18:3857 and EPSG:6.18.3:3857 all name EPSG 3857, and the version says which edition of the register was consulted rather than which system is meant.

Parameters
textThe identifier as the document spells it.
Returns
The authority and code; invalid when text names neither.
Note
Axis order is deliberately not answered here. Whether EPSG:4326 is read latitude-first depends on the authority's definition of it, which needs a coordinate database this library does not carry — the hosts have one and should be asked. The single exception is CrsIdentifier::isCrs84().
Here is the call graph for this function:
Here is the caller graph for this function:

◆ parseWcsCapabilities()

WcsCapabilities HydroCouple::Ogc::parseWcsCapabilities ( const QByteArray & xml)
nodiscard

Reads a WCS GetCapabilities response.

Parameters
xmlThe response body.
Returns
What the server offers; check ok first.
Here is the call graph for this function:

◆ parseWcsCoverageDescription()

WcsCoverageDescription HydroCouple::Ogc::parseWcsCoverageDescription ( const QByteArray & xml)
nodiscard

Reads a WCS 2.0 DescribeCoverage response.

Parameters
xmlThe response body.
Returns
The first coverage described; check ok first.
Here is the call graph for this function:

◆ parseWfsCapabilities()

WfsCapabilities HydroCouple::Ogc::parseWfsCapabilities ( const QByteArray & xml)
nodiscard

Reads a WFS GetCapabilities response.

Parameters
xmlThe response body.
Returns
What the server offers; check ok first.

◆ parseWmsCapabilities()

WmsCapabilities HydroCouple::Ogc::parseWmsCapabilities ( const QByteArray & xml)
nodiscard

Reads a WMS GetCapabilities response.

Nested layers inherit from their parents, which is the one thing a casual reading of the document gets wrong. WMS declares a tree, and the standard (OGC 06-042 §7.2.4.8) says a child layer adds to its parent's coordinate systems, styles and bounding box rather than replacing them. Servers rely on it heavily: on a common OSM WMS the root carries twenty-four coordinate systems and every drawable layer beneath it declares none of its own. Read flat, every one of those layers looks as though it can be drawn in no coordinate system at all.

The response may also be an exception report, and servers send those with HTTP 200 and an image content type, so the only way to know is to look. ok is then false and message carries what the server said.

Parameters
xmlThe response body.
Returns
What the server offers; check ok first.

◆ parseWmtsCapabilities()

WmtsCapabilities HydroCouple::Ogc::parseWmtsCapabilities ( const QByteArray & xml)
nodiscard

Reads a WMTS GetCapabilities response.

Parameters
xmlThe response body.
Returns
What the server offers; check ok first.

◆ preferredOutputFormat()

QString HydroCouple::Ogc::preferredOutputFormat ( const WfsFeatureType & type,
const QStringList & serviceFormats )
nodiscard

The best format to ask type for, of those it offers.

GeoJSON when there is any, because it needs no schema to read and carries its own coordinate system; GML otherwise, which every WFS has and which needs a driver. Empty when the type offers neither, which is a service this application cannot read.

Parameters
typeThe feature type.
serviceFormatsWhat the service offers for types that name none.
Here is the call graph for this function:

◆ Q_DECLARE_LOGGING_CATEGORY()

HYDROCOUPLEOGC_EXPORT HydroCouple::Ogc::Q_DECLARE_LOGGING_CATEGORY ( ogcHttp )

Everything this library logs, off unless asked for.

What a service needs before it will answer.

Held in memory for as long as a layer is open and never written to a project file: a project is shared, and a service password is not.

Headers to send, keyed by header name.

Sent as written; HTTP header names are case-insensitive, so a "referer" stored in lower case reaches a server gating on the Referer header unchanged. QGIS stores the same map under a http-header/ settings group, and openswmm.gui followed it, so connection files exported from any of the three interchange.

Puts these on request.

Basic authentication is written as a header rather than left to QNetworkAccessManager's authenticationRequired signal, because that signal costs a round trip per request and fires on a thread the caller may not be on.

A stable fingerprint of these credentials.

Requests are only shared between callers when they agree, and this is what "agree" is decided on. It is a digest rather than the values themselves so that no map anywhere in this library is keyed by a password.

◆ redactedUrl()

QString HydroCouple::Ogc::redactedUrl ( const QUrl & url)
nodiscard

url with anything secret in it replaced.

Half of these services are addressed with the key in the query string, so logging a request URL as it stands publishes the key to anyone who later reads the log — which is exactly what the implementation this replaces did, unconditionally and at every zoom. Userinfo goes, and so does the value of any query item whose name looks like a secret.

Here is the caller graph for this function:

◆ wcsExceptionText()

QString HydroCouple::Ogc::wcsExceptionText ( const QByteArray & body)
nodiscard

What an OGC exception report says, if that is what this is.

Worth asking before concluding anything else about a failed request. A WCS answers a malformed parameter with an exception report under an error status – rasdaman uses 404 for InvalidAxisLabel – which is indistinguishable from "no such endpoint" unless the body is read. A client that does not read it retries the request as an older protocol version and reports the wrong reason for the wrong failure.

Parameters
bodyThe response body.
Returns
The exception text, or empty when this is not a report.
Here is the caller graph for this function:

◆ wmsAxisOrderIsLatitudeFirst()

bool HydroCouple::Ogc::wmsAxisOrderIsLatitudeFirst ( const QString & crs,
const QString & version )
nodiscard

Whether crs is written latitude first under WMS version.

Parameters
crsThe system, in any of the spellings servers use.
versionThe version the capabilities document declared.
Here is the call graph for this function:
Here is the caller graph for this function: