The IDLnetOGCWMS::GetCapabilities function method retrieves an XML file containing layers describing geographic information from a remote OGC WMS server, writes the file to disk, and parses the file contents before returning. The XML file is written to the location specified by the CAPABILITIES_FILENAME property, and will be overwritten if this property value remains unchanged between GetCapabilities requests.
You can parse the contents of an existing XML file by setting the FROM_FILE keyword. This avoids having to download the same information as that which exists on disk.
The URL_PATH and URL_HOSTNAME properties must be set before requesting information from a remote WMS server. You can either set these properties manually or pass a URL to the IDLnetOGCWMS::ParseUrl method prior to making a request. If you are working with a proxy server, you must also set the PROXY_HOSTNAME and PROXY_PORT properties to the correct values.
This method returns only when one of the following occur:
- Completes retrieval and parsing of information from server
- Encounters an HTTP error
- Encounters an OGC exception
- Responds to a cancel request as specified in a callback return value
You can implement a callback to return status information during the request by setting the CALLBACK_FUNCTION property. You can also use a callback to cancel a request. See Using Callbacks with the IDLnetOGCWCS Object for details. This method will throw an error if the GetCapabilities request fails.
After this method returns, you must use IDLnetOGCWMS::GetLayers to return layer details. The GetCapabilities method accesses and parses the information from the server and returns a count containing the number of layers received, but does not provide immediate access to the detailed information. You can also use the IDLnetOGCWMS::GetServiceSection method to access information about service data contained in the XML file.
Syntax
Result = Obj->[IDLnetOGCWMS::]GetCapabilities ([, /DISABLE_INHERITANCE] [ ,FROM_FILE=string] [,SCHEMA_CHECKING=value] [, VALIDATION_MODE=value])
Return Value
Returns the number of layers received.
Arguments
None
Keywords
DISABLE_INHERITANCE
Set this keyword to a Boolean value indicating whether or not to disable layer inheritance as follows:
|
0 |
False - allow inheritance (the default)
|
|
1 |
True - disable inheritance
|
The OGC WMS standard specification defines which child layer tags can inherit from a parent layer. When inheritance is enabled (DISABLE_INHERITANCE=0), the returned layer structures will have inheritance rules applied to each layer as described in Inheritance of Layer Values. For example, if a child inherits its parents’ layer information, the child SRS value will be composed of an array that includes all the SRS values of all parents. When the inheritance rule is “Add,” duplicate values are ignored (not replicated).
FROM_FILE
Set this keyword to a string containing the full path and filename of an XML file to parse for layers and service data. This allows you use a previously downloaded capabilities file.
When you use the FROM_FILE keyword and the CALLBACK_FUNCTION property is set, status information will be returned when the XML file is first accessed and when parsing has ended. The entire file contents are parsed.
SCHEMA_CHECKING
XML Schemas describe the structure and allowed contents of an XML document. Schemas are more robust than, and are envisioned as a replacement for, Document Type Definitions (DTDs). Schemas are typically provided via a link to an external document, which must be downloaded before validation can occur.
Set this keyword to one of the following values to control the degree of error-checking the parser should perform:
|
0 |
Turn schema checking off: The XML file is not checked for errors. Use this setting to avoid the delays associated with schema checking. This is the default.
|
|
1 |
Check for fatal schema errors in the XML file: This setting requires more time since the XML file is checked against a WMS schema reference document accessed from the OGC server.
|
|
2 |
Check for fatal errors in the XML file and schema document: This setting checks both the XML file and the reference schema document for fatal errors, and requires a considerable amount of time.
|
VALIDATION_MODE
XML Document Type Definitions (DTDs) describe the structure and allowed contents of an XML document. A DTD can be embedded in an XML document or provided via a link to an external document, which must be downloaded before validation can occur. In most applications, schemas provide a more robust validation mechanism.
Set this keyword to one of the following values to control DTD-based validation of the XML document:
|
0 |
Turn DTD validation off: External DTDs are not loaded and the XML file is not checked for errors. Use this setting to avoid the delays associated with loading and checking an external DTD. This is the default.
|
|
1 |
Validate only if an embedded DTD or a link to an external DTD is provided.
|
|
2 |
Always perform validation. If this option is in force and no DTD is provided, every XML element in the document will generate an error.
|
Inheritance of Layer Values
The following tables (Number below and Inheritance) describe how the child layer elements inherit parent layer elements. See the following column descriptions for details.
Number
The Number column provides information on how many times each element may appear in a layer, either explicitly or through inheritance as follows:
|
Value |
Meaning |
|
1 |
Appears exactly once in each Layer
|
|
0/1 |
Appears either once or not at all
|
|
0+ |
Appears 0 or more times
|
|
1+ |
Appears one or more times
|
Inheritance
The Inheritance column indicates whether or how the element is inherited by child Layers as follows:
|
Value |
Meaning |
|
No |
Not inherited. If the element is defined as mandatory, each Layer element will include that element.
|
|
Replace |
Value can be inherited, but if defined by child, the value is replaced.
|
|
Add |
Values that may appear more than one time can be inherited from parent and added to any value(s) of the child. Any duplication by the child may be ignored.
|
Layer Element Inheritance in Version 1.1.1
When inheritance is enabled (DISABLE_INHERTANCE=0), use the following table to determine the type of allowable inheritance for a server supporting OGC WMS version 1.1.1.
|
Element |
Number
|
Inheritance
|
|
Layer |
0+ |
No |
|
Name |
1 |
No |
|
Title |
1 |
No |
|
Abstract |
0/1 |
No |
|
KeywordList |
0/1 |
No |
|
Style |
0+ |
Add |
|
SRS |
1+ |
Add |
|
LatLonBoundingBox
|
1 |
Replace |
|
BoundingBox |
0+ |
Replace |
|
Dimension |
0+ |
Add |
|
Extent |
0+ |
Replace |
|
Attribution |
0/1 |
Replace |
|
AuthorityUrl |
0+ |
Add |
|
Identifier |
0+ |
No |
|
MetadataUrl |
0+ |
No |
|
DataUrl |
0/1 |
No |
|
FeatureListUrl |
0/1 |
No |
|
ScaleHint |
0/1 |
Replace |
Layer Element Inheritance in Version 1.3.0
When inheritance is enabled (DISABLE_INHERTANCE=0), use the following table to determine the type of allowable inheritance for a server supporting OGC WMS version 1.3.0.
|
Element |
Number
|
Inheritance
|
|
Layer |
0+ |
No |
|
Name |
0/1a |
No |
|
Title |
1 |
No |
|
Abstract |
0/1 |
No |
|
KeywordList |
0/1 |
No |
|
Style |
0+ |
Add |
|
CRS |
1+b |
Add |
|
Ex_GeographicBoundingBox
|
1b |
Replace |
|
BoundingBox |
1+b |
Replace |
|
Dimension |
0+ |
Replace |
|
Attribution |
0/1 |
Replace |
|
AuthorityUrl |
0+ |
Add |
|
Identifier |
0+ |
No |
|
MetadataUrl |
0+ |
No |
|
DataUrl |
0/1 |
No |
|
FeatureListUrl |
0/1 |
No |
|
MinScaleDenominator
|
0/1 |
Replace |
|
MaxScaleDenominator
|
0/1 |
Replace |
aSee Layer Names and Titles for more information.
b May be 0 only if a value is inherited from a parent layer.
Examples
See IDLnetOGCWMS::GetLayers for an example that parses a URL and then calls GetCapabilities to return an XML file. A callback function is used to return status information about the query. Also see Sample WMS Browser.
Version History
See Also
IDLnetOGCWMS::GetLayers, IDLnetOGCWMS::GetServiceSection