TSLWMTSServiceSettingsCallbacks Class Reference

Detailed Description

This abstract class defines all the potential callbacks that will be sent by the TSLWMTSDataLayer when it attempts to load a Web Map Tile Service. The order of the methods is the order in which each will be called depending on the validity of the layer settings.

If the service metadata is loaded successfully then the onCapabilitiesLoaded method will be called first. Provided is a modifiable TSLWMTSServiceInfo instance. The user should set all necessary settings on the object, such as the service layers that they wish to be visible, which tile matrix sets to use, and any required layer dimensions and/or layer style values.

If the service metadata is not successfully loaded then the onCapabilitiesLoadFailure method will be called first instead. This callback can however be called later in the callback process to denote an error that was not originally determined.

Assuming the onCapabilitiesLoaded method was called, and the user does not return false to indicate a failure, the layer settings are checked in the following order:

• onNoVisibleLayers - None of the TSLWMTSServiceLayers are visible
• onNoCommonCRSinVisibleLayers - The set of visible layers do not have a common Coordinate Reference System (CRS), as retrieved from their selected tile matrix sets.
• onSelectedCRSNotSupported - Although there is a common CRS across the selected tile matrix sets, MapLink either does not support it or cannot match it to a supported CRS. (Note MapLink only supports known EPSG systems and CRS:84)
• onChoiceOfServiceCRSs - Multiple common CRSs are defined for the visible layers, the user should indicate which CRS to use.
• onChoiceOfRequestFormats - There are multiple supported GetTile request formats available. The user should indicate which format to use.
• onUserLinearTransformInvalid - The user provided linear transform cannot fit the entirety of the visible layers' data into the coordinate space

If the user does not return false when any of the above methods are called, then the data layer will recheck the reason for the call. If the test still fails then the method will be called again, if not then the checks will continue to the next test. The user should keep this in mind as this could cause an infinite loop should the user not rectify the problem. Returning false from any of these methods will cause loading to fail and the callback loop to be cancelled.

Assuming the service loaded successfully, then the final callback will be made: onServiceSettingsComplete.

Public Types
enum	CapabilitiesLoadFailureReason {   LoadingFailedInternetSettings = 0 , LoadingFailedLoadFailed = 1 , LoadingFailedParseFailure = 2 , LoadingFailedServiceUnsupported = 3 ,   LoadingFailedUnableToDetermineExtent = 4 }

Public Member Functions
virtual bool	onCapabilitiesLoaded (TSLWMTSServiceInfo *serviceInfo)=0
virtual void	onCapabilitiesLoadFailure (CapabilitiesLoadFailureReason reason)=0
virtual bool	onNoVisibleLayers (TSLWMTSServiceInfo *serviceInfo)=0
virtual int	onChoiceOfServiceCRSs (const char **crsChoices, int noOfChoices)=0
virtual bool	onNoCommonCRSinVisibleLayers (TSLWMTSServiceInfo *serviceInfo)=0
virtual bool	onSelectedCRSNotSupported (TSLWMTSServiceInfo *serviceInfo)=0
virtual int	onChoiceOfRequestFormats (TSLWMTSServiceLayer *layer, const char **formatChoices, int numFormatChoices)=0
virtual bool	onUserLinearTransformInvalid ()=0
virtual bool	onServiceSettingsComplete ()=0
virtual	~TSLWMTSServiceSettingsCallbacks ()=0

Member Enumeration Documentation

CapabilitiesLoadFailureReason

enum TSLWMTSServiceSettingsCallbacks::CapabilitiesLoadFailureReason

Enumeration that describes some of the potential reasons why the WMTS data layer may fail to load a service:

Enumerator
LoadingFailedInternetSettings	Check your Internet settings as an error was reported.
LoadingFailedLoadFailed	Failed to load the service level metadata. Perhaps the service is unavailable or inaccessible.
LoadingFailedParseFailure	Failed to parse the service level metadata. It may be invalid.
LoadingFailedServiceUnsupported	The service is not supported.
LoadingFailedUnableToDetermineExtent	The data layer failed to determine the required combined extent of the visible layers.

Constructor & Destructor Documentation

~TSLWMTSServiceSettingsCallbacks()

TSLWMTSServiceSettingsCallbacks::~TSLWMTSServiceSettingsCallbacks ( )

inlinepure virtual

Additional Declarations

Member Function Documentation

onCapabilitiesLoaded()

virtual bool TSLWMTSServiceSettingsCallbacks::onCapabilitiesLoaded ( TSLWMTSServiceInfo * serviceInfo )

pure virtual

This callback will be made when the service metadata has been successfully loaded. The client application should set the layer visibilities and tile matrix sets. Dimension and style values can be set as required.

NOTE: The client application should not store the value of serviceInfo. It should only be modified during a callback to the client application. If it is modified outside of one of these callbacks then the changes will either be ignored or could cause a crash.

Parameters

serviceInfo

The service metadata.

The client application should return true to continue the load, false to cancel and remove all data.

onCapabilitiesLoadFailure()

virtual void TSLWMTSServiceSettingsCallbacks::onCapabilitiesLoadFailure ( CapabilitiesLoadFailureReason reason )

pure virtual

This callback will be made if the WMTS data layer fails to load or parse the service capabilities and is intended to provide some feedback as to the reason.

onChoiceOfRequestFormats()

virtual int TSLWMTSServiceSettingsCallbacks::onChoiceOfRequestFormats ( TSLWMTSServiceLayer * layer, const char ** formatChoices, int numFormatChoices )

pure virtual

This callback will be triggered if the data layer has a choice of possible GetTile formats to choose from.

The default implementation would be to return 0, indicating the format at position 0 in the array of choices passed.

Parameters

layer	The service layer
formatChoices	An array of strings containing the format values as returned in the service metadata. The order will be the same as the service metadata after unsupported formats have been weeded out.
numFormatChoices	The size of the array specified by the formatChoices parameter.

The client application should return the index of the format that they wish to use. If the returned index is invalid then the load will be cancelled and all loaded data removed.

onChoiceOfServiceCRSs()

virtual int TSLWMTSServiceSettingsCallbacks::onChoiceOfServiceCRSs ( const char ** crsChoices, int noOfChoices )

pure virtual

Indicates the changes made to the layer settings under an onCapabilitiesLoaded callback left a choice of possible coordinate reference systems to use.

The default implementation would be to choose the CRS at index 0.

Parameters

crsChoices	An array of strings containing the crs values.
noOfChoices	The size of the array passed as crsChoices.

Returns

The client application should return the index of the CRS that wish to use. If the returned index is invalid then the load will be cancelled and all loaded data removed.

onNoCommonCRSinVisibleLayers()

virtual bool TSLWMTSServiceSettingsCallbacks::onNoCommonCRSinVisibleLayers ( TSLWMTSServiceInfo * serviceInfo )

pure virtual

Indicates that the changes made to the layer settings under an onCapabilitiesLoaded callback left 2 or more layers visible, but that the selected tile matrix sets do not have a common coordinate reference system between them.

The coordinate reference system of a tile matrix set can be retrieved with TSLWMTSServiceTileMatrixSet::supportedCRS; all selected tile matrix sets (of visible layers) should have the same coordinate reference system.

Parameters

serviceInfo

The service metadata.

The client application should return true to retry the load, false to cancel and remove all data.

onNoVisibleLayers()

virtual bool TSLWMTSServiceSettingsCallbacks::onNoVisibleLayers ( TSLWMTSServiceInfo * serviceInfo )

pure virtual

Indicates the changes made to the layer settings under an onCapabilitiesLoaded callback left no layers visible.

Parameters

serviceInfo

The service metadata.

The client application should return true to retry the load, false to cancel and remove all data.

onSelectedCRSNotSupported()

virtual bool TSLWMTSServiceSettingsCallbacks::onSelectedCRSNotSupported ( TSLWMTSServiceInfo * serviceInfo )

pure virtual

Indicates that the changes made to the layer settings under an onCapabilitiesLoaded callback left 1 or more layers visible, but that the selected tile matrix sets' shared coordinate reference system is not supported.

Parameters

serviceInfo

The service metadata.

The client application should return true to retry the load, false to cancel and remove all data.

onServiceSettingsComplete()

virtual bool TSLWMTSServiceSettingsCallbacks::onServiceSettingsComplete ( )

pure virtual

This callback will be made to indicate the layer settings changed under an on CapabilitiesLoaded callback (or subsequent error callbacks) were accepted and valid. It should be overridden to tidy up any resources allocated.

The client application should return true to continue the load, false to cancel and remove all data.

onUserLinearTransformInvalid()

virtual bool TSLWMTSServiceSettingsCallbacks::onUserLinearTransformInvalid ( )

pure virtual

This callback will be made if the user linear transforms specified the the TSLWMTSDataLayer could not fit the entirety of the loaded data into the coordinate space.

The client application should return true to retry the load, false to cancel and remove all data.