TSLS63DataClient Class Reference

Inheritance diagram for TSLS63DataClient:

Detailed Description

This interface class defines the callbacks that are issued by the S63SDK for both media ingest and display of S63 data.

For media ingest, the following callbacks are used: attachmentForCell cellCancelled coordinateSystemForCell currentCellVersion currentTime loadCellIntermediaryData loadCellTMFData locateCatalogueForCell notifyError notifyWarning populateEntityInformation progress storeIngestedCell

For display the following callbacks are used: currentTime loadCellTMFData notifyError notifyWarning

Public Member Functions
virtual void	attachmentForCell (const char *filename, const char *cellName, const char *dataServerID, TSLSimpleString &attachmentID, TSLSimpleString &attachmentLookup)=0
virtual bool	cellCancelled (const char *cellName, const char *dataServerID, const char **replacementCells, int numberOfReplacementCells)=0
virtual const TSLCoordinateSystem *	coordinateSystemForCell (const char *cellName, const char *dataServerID)=0
virtual int	currentCellVersion (const char *cellName, const char *dataServerID)=0
virtual TSLTimeType	currentTime ()=0
virtual TSLS63CellLoadResultEnum	loadCellIntermediaryData (const char *cellName, const char *dataServerID, TSLS63EncryptedData *intermediaryData)=0
virtual TSLS63CellLoadResultEnum	loadCellTMFData (const char *cellName, const char *dataServer, TSLS63EncryptedData *tmfData)=0
virtual bool	locateCatalogueForCell (const char *cellName, const char *dataServerID, int exchangeSetNumber, TSLSimpleString &locationOfCatalogue)=0
virtual void	notifyError (TSLS63ErrorCodeEnum s63ErrorCode, const char *cellName, const char *dataServerID, const char *additionalInformation=NULL)=0
virtual void	notifyWarning (const char *additionalInformation, const char *cellName=NULL, const char *dataServerID=NULL)=0
virtual void	populateEntityInformation (TSLEntity *entity, TSLEntitySet *entitySet, const char *cellName, const char *dataServerID)=0
virtual bool	progress (double percentOfExchangeSetDone, double percentOfCurrentCellDone)=0
virtual void	storeIngestedCell (const TSLS63EncryptedData *cellTMF, const TSLS63EncryptedData *cellIntermediaryData, const char *cellName, const char *dataServerID, const TSLGeodeticExtent &cellExtent, int cellEdition, int cellUpdateNumber)=0
virtual void	ingestedCellInformation (const TSLS63CellInformation &cellInformation)
virtual TSLS63DataClientType	type ()
virtual	~TSLS63DataClient ()=0

Constructor & Destructor Documentation

~TSLS63DataClient()

TSLS63DataClient::~TSLS63DataClient ( )

inlinepure virtual

Member Function Documentation

attachmentForCell()

virtual void TSLS63DataClient::attachmentForCell ( const char * filename, const char * cellName, const char * dataServerID, TSLSimpleString & attachmentID, TSLSimpleString & attachmentLookup )

pure virtual

This callback will be invoked when the ingest discovers an attachment for a cell. You should populate the attachmentLookup parameter with a unique value that will allow lookup of the attachment at display time.

Parameters

filename	The full path to the filename of the attachment.
cellName	The name of the cell associated with the attachment.
dataServerID	The two-character ID of the data server that issued the cell.
attachmentID	This should be set to a two-character ID that can be used to retrieve the attachment lookup information at display time from an entity's dataset.
attachmentLookup	This should be set to a unique value that will allow lookup of the attachment at runtime.

cellCancelled()

virtual bool TSLS63DataClient::cellCancelled ( const char * cellName, const char * dataServerID, const char ** replacementCells, int numberOfReplacementCells )

pure virtual

This callback will be invoked when a cell within an exchange set is cancelled. A cancelled cell will receive no further updates in future exchange sets and so should not be used for navigation purposes. A cancelled cell may optionally be retained in the exchange set, in which case it will continue to be available for display.

Parameters

cellName	The name of the cell that has been cancelled.
dataServerID	The two-character ID of the data server that issued the cell.
replacementCells	A cancelled cell may be replaced by one or more cells. This array contains the names of these replacement cells.
numberOfReplacementCells	The number of items in the replacementCells array.

Return true to keep the cancelled cell in the exchange set, or false to remove it.

coordinateSystemForCell()

virtual const TSLCoordinateSystem * TSLS63DataClient::coordinateSystemForCell ( const char * cellName, const char * dataServerID )

pure virtual

This callback will be invoked during media ingest when a new base cell is ingested. An implementation of this method should return the TSLCoordinate System object that describes the coordinate system that the given cell is in. This coordinate system should have the TMC to MU value configured appropriately for the source data.

This callback will not be invoked if the return value from currentCell Version() indicated that a previous version of the cell exists. In this case the loadCellTMFData() callback will be invoked for the cell instead.

Parameters

cellName	The name of the cell
dataServerID	The two character ID of the data server that issued the cell.

currentCellVersion()

virtual int TSLS63DataClient::currentCellVersion ( const char * cellName, const char * dataServerID )

pure virtual

This callback will be invoked during the media ingest, started by TSLMedia IngestManager::loadExchangeSet(). The implementation of this function should return the currently held version for the given cell that was imported during a previous ingest. If no previous version of the cell was ingested or no information is held on the current version of the cell then this method should return -1.

Parameters

cellName	The name of the cell for which the last imported version number should be returned.
dataServerID	The two-character ID of the data server that issued the cell.

currentTime()

virtual TSLTimeType TSLS63DataClient::currentTime ( )

pure virtual

This callback will be invoked during media ingest and display of S63 data. The implementation of this method should return the current time expressed in UTC (number of seconds elapsed since midnight (00:00:00), January 1, 1970).

It is the OEM's responsibility to ensure the time is accurate by checking the time returned from the system clock against an external source such as a GPS unit if possible.

ingestedCellInformation()

void TSLS63DataClient::ingestedCellInformation ( const TSLS63CellInformation & cellInformation )

inlinevirtual

This callback will be invoked for each base cell and update that is ingested by the media ingest manager. Unlike the storeIngestedCell callback it will be invoked for every update to a cell present in a dataset, rather than once after the updates are applied to a cell.

This callback only provides additional information about each cell and update ingested into the data store, applications that do not require this information do not need to implement this callback.

Parameters

cellInformation

Contains additional information about the cell ingested into the data store.

loadCellIntermediaryData()

virtual TSLS63CellLoadResultEnum TSLS63DataClient::loadCellIntermediaryData ( const char * cellName, const char * dataServerID, TSLS63EncryptedData * intermediaryData )

pure virtual

This callback will either be invoked during the media ingest process when the return value from currentCellVersion() indicated that an older version of the cell was ingested previously. The implementation of this method should populate the intemediaryData argument with the data that represents the encrypted intermediary data that was returned by the last ingest of that cell.

Parameters

cellName	The name of the cell for which the result of the last ingest is wanted.
dataServerID	The two character data server ID of the data server that issued the cell.
intermediaryData	This should be populated with the intermediary data of the cell in question.

The implementation of this function should return the appropriate value from the TSLS63CellLoadResultEnum enumeration describing the result of the cell loading. If TSLS63CellLoadResultDisregardAllCells is returned during an ingest then the ingest will be aborted.

loadCellTMFData()

virtual TSLS63CellLoadResultEnum TSLS63DataClient::loadCellTMFData ( const char * cellName, const char * dataServer, TSLS63EncryptedData * tmfData )

pure virtual

This callback will either be invoked during the runtime display and decryption process when MapLink requires the encrypted TMF data for that cell. The implementation of this method should populate the tmfData argument with the data that represents the encrypted tmf data that was returned by the last ingest of that cell.

Parameters

cellName	The name of the cell for which the result of the last ingest is wanted.
dataServer	The two character data server ID of the data server that issued the cell.
tmfData	This should be populated with the TMF data of the cell in question.

The implementation of this method should return the appropriate value from the TSLS63CellLoadResultEnum enumeration describing the result of the cell loading. If TSLS63CellLoadResultDisregardAllCells is returned during an ingest then the ingest will be aborted.

locateCatalogueForCell()

virtual bool TSLS63DataClient::locateCatalogueForCell ( const char * cellName, const char * dataServerID, int exchangeSetNumber, TSLSimpleString & locationOfCatalogue )

pure virtual

This callback will be invoked for each cell that will be ingested. The implementation of this method should populate the locationOfCatalogue and coordinateSystemToUseForCell fields with the full path to the location of the CATALOG.031 file to use for that cell. If the CATALOG.031 file cannot be found the implementation of this method should return false.

Parameters

cellName	The name of the cell that is to be ingested.
dataServerID	The two-character ID of the data server that issued the cell.
exchangeSetNumber	The disk number in the exchange set for the cell on which the CATALOG.031 file should be located.
locationOfCatalogue	This should be set to the location of the CATALOG.031 file associated with the given cell.

notifyError()

virtual void TSLS63DataClient::notifyError ( TSLS63ErrorCodeEnum s63ErrorCode, const char * cellName, const char * dataServerID, const char * additionalInformation = NULL )

pure virtual

This method will be called whenever MapLink encounters an error that is described in the S63 standard.

Parameters

s63ErrorCode	The error code from the S63 standard that defines the event that has occurred. See the documentation for TSLS63ErrorCodeEnum and the S63 specification for more information on these errors.
cellName	For errors that relate to a particular cell this argument will contain the name of the cell for which the error occurred. If no cell is associated with the error this argument will be NULL.
dataServerID	For errors that relate to a particular data server this argument will contain the two-character ID of the data server for which the error occurred. If no data server is associated with the error this argument will be NULL.
additionalInformation	Any additional information about the cause error.

notifyWarning()

virtual void TSLS63DataClient::notifyWarning ( const char * additionalInformation, const char * cellName = NULL, const char * dataServerID = NULL )

pure virtual

This method will be called whenever MapLink encounters an error that is described in the S63 standard but for which there is not an associated S63 error code. According to the S63 standard, the user should still be notified of these errors.

Parameters

additionalInformation	Any additional information about the cause error.
cellName	For errors that relate to a particular cell this argument will contain the name of the cell for which the error occurred. If no cell is associated with the error this argument will be NULL.
dataServerID	For errors that relate to a particular data server this argument will contain the two-character ID of the data server for which the error occurred. If no data server is associated with the error this argument will be NULL.

populateEntityInformation()

virtual void TSLS63DataClient::populateEntityInformation ( TSLEntity * entity, TSLEntitySet * entitySet, const char * cellName, const char * dataServerID )

pure virtual

This callback will be invoked for each entity created from an ingested cell. The implementation of this method should populate the feature ID, render level and any other information you consider necessary.

Any associated primitives for the entity can be added to the provided TSLEntitySet.

Parameters

entity	The entity to populate with additional information.
entitySet	A TSLEntitySet to which associated primitives can be added.
cellName	The name of the cell which contains the entity.
dataServerID	The two character ID of the data server that issued the cell.

progress()

virtual bool TSLS63DataClient::progress ( double percentOfExchangeSetDone, double percentOfCurrentCellDone )

pure virtual

This callback will be invoked during media ingest to report on the progress of the ingest for both the exchange set being imported and the current cell being processed within the set.

Parameters

percentOfExchangeSetDone	This will contain the percentage of the current exchange set that has been ingested so far. This indicates the amount of data the ingest still has to process
percentOfCurrentCellDone	This will contain the percentage of the ingest for the current cell being processed that has been completed. This value includes the application of any applicable updates to the cell.

To abort the entire ingest, return false. To continue the ingest return true.

storeIngestedCell()

virtual void TSLS63DataClient::storeIngestedCell ( const TSLS63EncryptedData * cellTMF, const TSLS63EncryptedData * cellIntermediaryData, const char * cellName, const char * dataServerID, const TSLGeodeticExtent & cellExtent, int cellEdition, int cellUpdateNumber )

pure virtual

This callback will be invoked after a cell has been ingested and the result needs to be stored. This will happen for each cell ingested by the manager.

Parameters

cellTMF	This contains the encrypted TMF to be stored. This memory is owned by the media ingest manager. MapLink will require this data both when displaying the cell and when importing updates to the cell.
cellIntermediaryData	This contains the encrypted intermediary data to be stored. This memory is owned by the media ingest manager. MapLink will require this data when applying updates to the cell during a future ingest. This may be NULL if the cell has been cancelled but was kept within the exchange set. If this happens the NULL value does not imply that the cell should be deleted from the OEM's store.
cellName	The name of the cell.
dataServerID	The two-character ID of the data server that issued the cell.
cellExtent	The extent of the cell in latitude/longitude.
cellEdition	The base edition of the cell.
cellUpdateNumber	The update number of the last cell update ingested. This will be required when updates for a cell are discovered during a subsequent ingest so that applicable updates to the cell held by the OEM can be determined.

type()

TSLS63DataClientType TSLS63DataClient::type ( )

inlinevirtual

Returns the type of data client which is been instantiated.

Reimplemented in TSLS57DataClient.