An IDLnetOGCWCS object lets you access a Web Coverage Service (WCS) server that supports the Open Geospatial Consortium (OGC) standards. The OGC is an international group working to develop standards for the exchange of geospatial content and services including specifications for web delivery of data that combines location and geospatial information.
For additional information on IDL’s WCS features, see the following sections:
Note: A sample IDL program included in the IDL distribution provides a generic WCS browser that lets you peruse and request coverages from a remote OGC server. See Sample WCS Browser for details.
Superclasses
None
Creation
See IDLnetOGCWCS::Init.
Properties
Objects of this class have the following properties. See IDLnetOGCWCS Properties for details on individual properties.
Methods
This class has the following methods:
Examples
See the following methods for examples:
Sample WCS Browser
The IDL distribution includes a sample program that allows you to enter a working URL to an OGC server and then call GetCapabilities, DescribeCoverage and GetCoverage from within the user interface. You can modify property values and query characteristics to return the desired data. To run the browser program, enter OGC_WCS at the command line. See the browser help for more information.
Tip: You can use the example IDL OGC WCS Browser as a template for creating an application that queries a remote WCS server. This example is located in the IDL_DIR\examples\ogc\wcs directory where IDL_DIR is the directory where you have installed IDL. Running the example lets you parse a known, working URL to an OGC WCS server, and then make GetCapabilities, DescribeCoverage and GetCoverage requests. By default, returned files are written to your application user directory, a subdirectory of your home directory.
Version History
Web Coverage Service (WCS) Overview
A request for coverage data from an OGC WCS server involves three main requests: GetCapabilities, DescribeCoverage, and GetCoverage. The following describes these operations in terms of the IDLnetOGCWCS object:
- GetCapabilities: A general query that returns information about what types of requests are allowed and available. This includes service and summary information about data collections that are contained in “coverage offering briefs,” which are transmitted in an XML file that is written to disk.
- DescribeCoverage: A request that asks for detailed information about one or more specific coverages where each coverage is a data collection. The server returns details about the coverage(s) in an XML file that is written to disk.
- GetCoverage: A request for data relating to a specific coverage. The server transmits a copy of the raw data, containing values or properties of a set of geographic locations, in a file that is written to disk.
For details on how to use the IDLnetOGCWCS object properties and methods to request and receive information from an OGC server, see Making OGC WCS Server Requests. Also see Sample WCS Browser for information about the IDL OGC WCS Browser, a sample program included in the IDL distribution.
Additional OGC Web Coverage Service Resources
The Open Geospatial Consortium web site provides complete details on the Web Coverage Service protocol including the WCS specification and schema documents. You may find the following documents helpful if you need additional WCS resources. See OGC web site (https://www.ogc.org/) to search for these and other resource files.
Document |
Description |
Specification |
OGC Web Coverage Service, Version 1.0.0, Ref# OGC 05-076r6, 2005-10-14
|
Schema Definition Documents
|
wcsCapabilities.xsd
|
XML schema definition used by the remote server when creating a GetCapabilities response, which contains one or more coverage offering briefs
|
describeCoverage.xsd
|
XML schema definition used by the remote server when creating a DescribeCoverage response, which contains one or more coverage offerings
|
owsBase.xsd
|
XML schema definition containing base types used in the wcsCapabilities.xsd and describeCoverage.xsd
|
values.xsd
|
XML schema definition containing base types used in the wcsCapabilities.xsd and describeCoverage.xsd
|
gml4wcs.xsd
|
XML schema definition containing GML types used in the wcsCapabilities.xsd, describeCoverage.xsd and owsBase.xsd
|
Supported OGC WCS Version
This object supports version 1.0.0 of the OGC WCS standard. The IDLnetOGCWCS object conforms to the OGC WCS standard and is designed to communicate with OGC WCS compliant servers.
Note: Since this object is designed as an OGC WCS client, OGC WCS certification is not applicable. Compliance testing and certification is valid only for WCS servers.
Making OGC WCS Server Requests
This section outlines the steps required to query and return information from an OGC server. The goal is to return a data file containing a specific geospatial coverage as unrendered data. A coverage is gridded data that typically has a 1-, 2-, or 3-axis spatial coordinate reference system. Broadly, an information request from a WCS sever requires determining what data is available from a server (coverage offering briefs), determining what data collection (coverage offerings) from which you want to request data (a coverage), making the requests, and returning unrendered data.
Note: You can implement a callback to return information about the status of requests. See Using Callbacks with the IDLnetOGCWCS Object for details.
After you create an IDLnetOGCWCS object, you will need to complete the following steps:
-
Identify the WCS server. The easiest way to do this is to pass a working URL to the IDLnetOGCWCS::ParseUrl method, which sets the required URL_HOSTNAME and URL_PATH properties. Alternately, you can manually set properties related to the URL. See Translating a URL into Property Values for information on which URL components belong to which IDLnetOGCWCS properties. If you are working with secure WCS servers, see HTTP Authentication, Security and Encoding for additional information.
- Determine what information is available on the WCS server by making a GetCapabilities request. This typically returns and parses an XML file that contains brief information about the available coverages. See IDLnetOGCWCS::GetCapabilities for details. You can modify the CAPABILITIES_FILENAME property to define the location this file is stored.
- Return the information contained in the coverage offering briefs by calling IDLnetOGCWCS::GetCoverageOfferingBriefs. You must call this method to return information for the specified coverage offering brief(s) in an IDL structure. The NAME field value of this structure is required to request additional information from an OGC server using the DescribeCoverage method, described next. If you wish, you can also call IDLnetOGCWCS::GetServiceSection to return service information from the XML file, but this is not necessary.
- Request detailed information about one or more coverage offerings by specifying a value for the NAME keyword in the IDLnetOGCWCS::DescribeCoverage call. The server will typically return an XML file containing detailed information about the coverage(s). You can modify the DESCRIBE_COVERAGE_FILENAME property to define the location this file is stored.
- Access the information in the XML file returned by DescribeCoverage by calling IDLnetOGCWCS::GetCoverageOffering. This returns a complex structure describing the offering details.
- Return data from the server by calling IDLnetOGCWCS::GetCoverage with a number of parameters describing the exact data to be returned. You can modify the COVERAGE_FILENAME property to define the location this file is stored.
- Model and render the data as defined by your application.
Translating a URL into Property Values
A valid WCS server URL is required to establish communication with an OGC WCS server. Additionally, IDLnetOGCWCS URL-related property values must be set before data can be successfully requested from a OGC WCS server. Either set the required properties manually (using SetProperty) or pass a URL to ParseURL. The IDLnetOGCWCS::ParseUrl method automatically parses a given URL and sets related property values.
Note: Regardless of how properties are set, the URL_HOSTNAME and URL_PATH properties must be set before calling the GetCapabilities, DescribeCoverage or GetCoverage methods.
The following table describes how the components of a given URL should be assigned to property values. Consider the following URL (which would typically exist on a single line):
http://my.hostname.com:8080/demo/cgi_path?customprefix&
Version=1.0.0&SERVICE=WCS&CustomMiddle&Request=GetCapabilities&
CustomSuffix
Components of this URL map to properties as follows.
The query portion of the URL passed to a WCS server (the parameter=value pairs following the ? character) always includes the following three parameters:
- Version takes its value from the WCS_VERSION property
- Service is set equal to “WCS” for the IDLnetOGCWCS object
- Request is one of “GetCapabilities” “DescribeCoverage”, or “GetCoverage” depending on the method in use
These three parameters are inserted into the URL automatically by IDL; any values specified for these parameters in the URL are ignored. They are not included when the URL_QUERY_PREFIX or URL_QUERY_SUFFIX properties are returned by the GetProperty method. Any query parameters that precede any of the three required parameters will be included in the URL_QUERY_PREFIX property by the ParseURL method; other nonrequired parameters will be included in the URL_QUERY_SUFFIX property.
Note: If not specified in the URL, property values besides URL_HOSTNAME and URL_PATH are set to default values. For example, the URL_PORT property defaults to 80 and the WCS_VERSION defaults to 1.0.0.
Using Callbacks with the IDLnetOGCWCS Object
Callbacks from the IDLnetOGCWCS object provide a way to transmit information back to the caller based on the status of a request made to a remote OGC WCS server. The value returned by the callback function is then used by the IDLnetOGCWCS object to determine whether to continue or abort the request.
The IDLnetOGCWCS object lets you define a single function (written in IDL) that will be called during a GetCapabilities, DescribeCoverage, or GetCoverage method call. If a callback function is specified via the CALLBACK_FUNCTION property, it is called in the following circumstances:
- For the IDLnetOGCWCS::GetCapabilities method, the callback function is called each time a packet is received from the OGC WCS server. If the FROM_FILE keyword is set, the callback function is called before and after the XML file is parsed.
- For the IDLnetOGCWCS::DescribeCoverage method, the callback function is called each time a packet is received from the OGC WCS server. If the FROM_FILE keyword is set, the callback function is called before and after the XML file is parsed.
- For the IDLnetOGCWCS::GetCoverage method, the callback function is called each time a packet of data is received from the OGC WCS server.
All methods invoke the callback function with an array of strings indicating status as the first parameter, an array of integers containing progress information as the second parameter, and with the value (if any) specified by the CALLBACK_DATA property as the third parameter. A callback function returns a value of type Int.
Cancelling a Request
The return value of the callback function should be an integer zero or one. If the return value is zero, a cancel message will be sent to the remote node. If the return value is one, the operation will continue.
Callback Routine Signature
A callback function is written in IDL and has the following signature:
Function Callback_Function_Name, StatusInfo, ProgressInfo, CallbackData
where
- Callback_Function_Name is the name of the callback function. This value is specified as the value of the CALLBACK_FUNCTION property.
- StatusInfo is an array of strings that contain status information about the operation. The status strings are provided for information and human inspection rather than for programmatic processing; the exact strings included in the array will depend on numerous factors including the status of the operation and the type of OGC WCS server.
- ProgressInfo is an array of five 64-bit long integers that contain progress information for the transfer:
- ProgressInfo[0] – Contains 1 (one) when the ProgressInfo array contains valid data, or 0 (zero) when the array does not contain valid data.
- ProgressInfo[1] – Contains the total number of bytes to be downloaded. This array element will contain 0 (zero) when the transfer encoding is “chunked.”
- ProgressInfo[2] – Contains the number of bytes that have been downloaded during the current transfer.
- ProgressInfo[3] – Contains the total number of bytes to be uploaded.
- ProgressInfo[4] – Contains the number of bytes that have been uploaded during the current transfer.
- CallbackData is the data specified via the CALLBACK_DATA property. The value of this property is passed to the callback function unmodified. If the CALLBACK_DATA property is unspecified, an integer zero is passed to the callback function as the value of this parameter.
The CallbackData parameter is useful for passing static information, such as the widget ID of a widget where the status information is displayed, from the IDLnetOGCWCS object to the callback routine.
For a simple example of using a callback to return additional status information, see IDLnetOGCWCS::GetCapabilities. The StatusInfo details are printed to the Output window.
HTTP Authentication, Security and Encoding
The following sections describe the IDLnetOGCWCS object’s support of HTTP protocols including:
HTTP Authentication
The IDLnetOGCWCS object supports the following HTTP authentication modes for WCS and proxy servers:
- Disabled—no authentication
- Basic—plain text transmission of username and password
- Digest—encrypted transmission of username and password
By default, AUTHENTICATION and PROXY_AUTHENTICATION properties are set to “Basic and Digest” option, meaning that either basic or digest authentication are supported. However, for this setting to be honored, the corresponding username and password properties must also be set:
HTTP Security
The IDLnetOGCWCS object also supports HTTPS through the implementation of Secure Socket Layer (SSL). With SSL encryption, all requests and responses are encrypted. When the URL_SCHEME property is set to “https”, use the SSL_CERTIFICATE_FILE, SSL_VERIFY_HOST, and SSL_VERIFY_PEER properties to define security-related parameters.
Note: If you receive a PRNG (Pseudo Random Number Generator) error when attempting to use HTTPS on UNIX, you need to install either dev/random or dev/urandom in order to generate secure keys.
HTTP Encoding
The IDLnetOGCWCS object supports compressed and encoded responses from a remote OGC WCS server. Supported encoding formats are:
See the ENCODE property for details.