 |
MapLink Pro 11.1.1.0.
Envitia MapLink Pro: The Ultimate Mapping Application Toolkit
|
|
MapLink Pro 11.1.1.0.
Envitia MapLink Pro: The Ultimate Mapping Application Toolkit
|
This class is used to control the conversion of S63 data into a form suitable for fast display by MapLink. It is capable of both ingesting new datasets as well as managing and applying updates to existing ingested data.
Before ingesting data the OEM should ensure that the cell permits corresponding to the data to be ingested are added to the media ingest manager via the addCellPermit() or addCellPermits() methods. The manager is capable of dealing with cell permits issued by different data servers for the same cell, thus it is perfectly acceptable to load all available cell permits into the manager prior to an ingest. For more information on cell permits see the documentation for TSLS63CellPermitCollection.
During ingest callbacks will be issued to the OEM via the TSLS63DataClient interface. For a description of which callbacks are used and when see the documentation for TSLS63DataClient.
Public Member Functions | |
| TSLS63MediaIngestManager (TSLS63DataClient *dataClient, const char *certificate, const TSLS63HWID *hw_id, TSLMapLinkVersion mapLinkVersion=TSL_CURRENT_MAPLINK_VERSION) | |
| bool | addCellPermit (const TSLS63CellPermit *permit, const char *dataServerIDForPermit=NULL) |
| bool | addCellPermits (const TSLS63CellPermitCollection *permitCollection, const char *dataServerIDForPermit=NULL) |
| void | dbgPerformCellSignatureVerification (bool performVerification) |
| void | dbgReferenceCellDirectory (const char *directory) |
| void | destroy () |
| bool | loadExchangeSet (const char *productsFile, const TSLS63SerialENCFile *serialFile, const char *certificate) |
| bool | loadExchangeSet (const char *productsFile, const TSLS63SerialENCFile *serialFile, const char *certificate, const char *filterConfigurationFile) |
| unsigned int | numberOfCellPermits (const char *dataServerIDForPermit) |
| unsigned int | numberOfDataServers () |
| const TSLS63CellPermit * | queryCellPermit (unsigned int index, const char *dataServerIDForPermit) |
| bool | queryDataServer (unsigned int index, TSLSimpleString &dataServerID) |
| bool | removeCellPermit (const char *dataServerID, const char *cellName) |
| bool | removeDataServer (const char *dataServerID) |
| void | setProcessingFlags (TSLFilterProcess processingFlags) |
| void * | operator new (size_t size) TSL_NO_THROW |
| void * | operator new (size_t size, char *filename, int line) |
Static Public Member Functions | |
| static bool | compareCertificatePublicKeys (const char *certificate1, const char *certificate2) |
| static bool | queryCertificate (const char *certificate, TSLTimeType &certificateValidFromDate, TSLTimeType &certificateExpiryDate, TSLSimpleString *certificateIssuer=0) |
| static bool | validateCertificateTimes (const TSLTimeType &validateTime, const TSLTimeType &validFromTime, const TSLTimeType &expiryTime) |
| TSLS63MediaIngestManager::TSLS63MediaIngestManager | ( | TSLS63DataClient * | dataClient, |
| const char * | certificate, | ||
| const TSLS63HWID * | hw_id, | ||
| TSLMapLinkVersion | mapLinkVersion = TSL_CURRENT_MAPLINK_VERSION ) |
Constructor for the TSLS63MediaIngestManager.
| dataClient | A pointer to an instance of the TSLS63DataClient interface to use during ingest of the data. |
| certificate | The full path of the IHO.CRT certificate file including filename. |
| hw_id | The hardware ID of the system the ingest process is running on. |
| mapLinkVersion | This defines the output format of the TMF files generated by and ingest. This can be used to generate files compatible with previous versions of MapLink. The default is to generate files at the current version. Note that versions of MapLink earlier than 5.4 will not be able to read the encrypted TMF files generated by an ingest. Therefore if a version earlier than 5.4 is provided here the output format will default to 5.4. |
| bool TSLS63MediaIngestManager::addCellPermit | ( | const TSLS63CellPermit * | permit, |
| const char * | dataServerIDForPermit = NULL ) |
Adds a single cell permit to the media ingest manager. The media ingest manager internally clones the given cell permit so the given cell permit does not have to exist for the duration of the ingest.
At minimum all cell permits relating to the data to be ingested must be added to the media ingest manager prior to performing the ingest.
| permit | The cell permit to add to the media ingest manager. |
| dataServerIDForPermit | Cell permits conforming to version 1.0 of the S63 standard may not contain the data server ID of the data server that issued the permit. This information is required by MapLink to perform an ingest using the permit. Therefore if this information is not contained within the permit the value passed in here will be used instead. The OEM can determine if this value needs to be provided by querying the data server ID from a loaded cell permit. If the value returned is NULL then the two character ID of the data server that issued the cell permit must be provided here. |
| bool TSLS63MediaIngestManager::addCellPermits | ( | const TSLS63CellPermitCollection * | permitCollection, |
| const char * | dataServerIDForPermit = NULL ) |
Adds all cell permits contained within the S63CellPermitCollection to the media ingest manager. The media ingest manager internally clones the given cell permits so the collection does not have to exist for the duration of the ingest.
At minimum all cell permits relating to the data to be ingested must be added to the media ingest manager prior to performing the ingest.
| permitCollection | The cell permit to add to the media ingest manager. |
| dataServerIDForPermit | Cell permits conforming to version 1.0 of the S63 standard may not contain the data server ID of the data server that issued the permit. This information is required by MapLink to perform an ingest using the permit. Therefore if this information is not contained within the permit the value passed in here will be used instead. The OEM can determine if this value needs to be provided by querying the data server ID from a loaded cell permit. If the value returned is NULL then the two character ID of the data server that issued the cell permit must be provided here. |
|
static |
This utility function is provided to the OEM to allow them to verify the X509 certificate supplied on the exchange set media against the SA certificate that they should store in a secure location on the data client's machine. It loads both X509 certificates and compares the public key provided by each, returning if they matched.
| certificate1 | The first certificate to compare |
| certificate2 | The second certificate to compare |
| void TSLS63MediaIngestManager::dbgPerformCellSignatureVerification | ( | bool | performVerification | ) |
This method is only required to verify that decryption of an erroneous ENC cell will fail due to either the decryption process resulting in invalid padded bytes in the cell, or a mismatch between the CRC between the decrypted and decompressed cell against the entry in the catalogue file.
During normal ingest of S63 data the signature file associated with each cell is checked for correctness and is then used to ensure that the cell itself has not been modified since it was issued.
The IHO mandated tests require that a system can detect that a particular set of ENC cells has been tampered with, but does not provide any associated signature files for these cells. Therefore, in order to ensure the correct error is reported for this data this method allows for the verification of cells from their corresponding signature files to be skipped.
If cell signature verification is disabled then no cells from the exchange set will be ingested beyond the point of performing the check regardless of whether the cell is verified or not. Cells that are not ingested due to the verification being disabled will log an error to the TSLErrorStack in the TSLErrorCategoryDebug category.
| performVerification | If false, cell signature verification will not be performed for any cells during an ingest. If true, cell signature verification will be performed for all cells during an ingest. |
The default behaviour is to always perform cell signature validation.
| void TSLS63MediaIngestManager::dbgReferenceCellDirectory | ( | const char * | directory | ) |
This method is only required to verify processing of a cell as part of the mandated IHO S63 tests and is not needed for performing any functionality relating to the TSLS63MediaIngestManager.
During normal ingest of S63 data a decrypted cell is checked for correctness by comparing the CRC checksum of the decrypted and decompressed cell against the expected value contained within the CATALOG.031 file for the cell. This check is sufficient to ensure that a cell has been correctly decrypted and decompressed and has not been modified since it was issued.
The IHO mandated tests specify an additional requirement when testing systems prior to deployment to perform a binary comparison of a decrypted cell against a reference cell provided as part of the test dataset. In order to accommodate this requirement, this method allows a directory to be specified to the media ingest manager that will contain the reference cells for the exchange set being ingested.
Reference cells will be expected to be located in the directory provided to this function and have the same filename as the cell being ingested from the exchange set. For example:
Reference directory: c:/reference Location of cell being ingested: c:/exchange_set/ENC_ROOT/GB/GB4X0000/1/0/GB4X0000.000 Expected location of reference cell: c:/reference/GB4X0000.000
Reference directory c:/data/ref Location of cell being ingested: c:/exchange_set/ENC_ROOT/NO5F1615.000 Expected location of reference cell: c:/data/ref/NO5F1615.000
Once a directory has been provided to the media ingest manager via this method, any future calls to loadExchangeSet() will check this directory for the reference cell corresponding to each cell being ingested, and will add a S63MI_DECRYPTED_COMPARISON_FAILED error to the TSLErrorStack if the reference cell cannot be located or does not match the decrypted cell. If the reference cell is identical to the cell decrypted during the ingest then no error is logged.
The S63MI_DECRYPTED_COMPARISON_FAILED error has the category TSLErrorCategory Debug meaning that it is easier to check for this error while ignoring other errors raised during ingest. Checking for a non-zero return from TSLErrorStack::size(TSLErrorCategoryDebug) after an ingest should suffice as currently no other errors that could be raised during ingest use that category.
Regardless of the result of this check the ingest of a cell is not affected and will continue as normal.
To prevent subsequent ingests from performing this check, invoke this method again passing in a NULL parameter.
The default behaviour is not to perform this check.
| directory | The directory that will contain the reference cells to compare against for the next ingest, or if NULL will disable the additional checking of decrypted cells. |
| void TSLS63MediaIngestManager::destroy | ( | ) |
Used to destroy instances of this class.
| bool TSLS63MediaIngestManager::loadExchangeSet | ( | const char * | productsFile, |
| const TSLS63SerialENCFile * | serialFile, | ||
| const char * | certificate ) |
Loads the exchange set specified by the given PRODUCTS.TXT file from the S63 dataset.
This method will ingest all cells contained within the dataset for which a valid cell permit is available. Cell permits can be added to the media ingest manager via the addCellPermit() and addCellPermits() methods.
During ingest callbacks will be issued via the TSLS63DataClient. For information on when these callbacks will be invoked see the class documentation.
| productsFile | The full path including filename to the PRODUCTS.TXT from the S63 dataset. |
| serialFile | The fill path including filename to the SERIAL.ENC file from the S63 dataset. |
| certificate | The Scheme Authority certificate .CRT file to use for validating S63 cells. In most situations this will be the same IHO.CRT as used in the constructor of the TSLS63MediaIngestManager. |
Note that it is possible for this method to return true when errors have been issued via the callbacks as S63 mandated errors are not considered fatal to the ingest process unless explicitly stated so.
| bool TSLS63MediaIngestManager::loadExchangeSet | ( | const char * | productsFile, |
| const TSLS63SerialENCFile * | serialFile, | ||
| const char * | certificate, | ||
| const char * | filterConfigurationFile ) |
Loads the exchange set specified by the given PRODUCTS.TXT file from the S63 dataset.
This method will ingest all cells contained within the dataset for which a valid cell permit is available. Cell permits can be added to the media ingest manager via the addCellPermit() and addCellPermits() methods.
During ingest callbacks will be issued via the TSLS63DataClient. For information on when these callbacks will be invoked see the class documentation.
| productsFile | The full path including filename to the PRODUCTS.TXT from the S63 dataset. |
| serialFile | The fill path including filename to the SERIAL.ENC file from the S63 dataset. |
| certificate | The Scheme Authority certificate .CRT file to use for validating S63 cells. In most situations this will be the same IHO.CRT as used in the constructor of the TSLS63MediaIngestManager. |
| filterConfigurationFile | The full path to the file which will be used to configure the S57 filter. |
Note that it is possible for this method to return true when errors have been issued via the callbacks as S63 mandated errors are not considered fatal to the ingest process unless explicitly stated so.
| unsigned int TSLS63MediaIngestManager::numberOfCellPermits | ( | const char * | dataServerIDForPermit | ) |
Query the number of cell permits added to the media ingest manager, for the given data server
| dataServerIDForPermit | The data server ID to use for the query. |
| unsigned int TSLS63MediaIngestManager::numberOfDataServers | ( | ) |
Query the number of data servers for which the ingest manager has loaded cell permits.
| void * TSLS63MediaIngestManager::operator new | ( | size_t | size | ) |
Allocation override for API redirection.
| void * TSLS63MediaIngestManager::operator new | ( | size_t | size, |
| char * | filename, | ||
| int | line ) |
When included in an MFC application in debug mode, the debug new expects this to be here. Override it and return the same as the normal one. The library must include it when compiled in release mode, since the user's application may be in debug mode.
| const TSLS63CellPermit * TSLS63MediaIngestManager::queryCellPermit | ( | unsigned int | index, |
| const char * | dataServerIDForPermit ) |
Query a cell permit from the media ingest manager, for the given data server
| index | The index of the cell permit to query |
| dataServerIDForPermit | The data server ID to use for the query. |
|
static |
This method checks that the location specified points to a valid X509 certificate file and extracts certain values for the certificate. A certificate is valid if it is a well formed X509 certificate file.
To validate if a specific time, such as the current time, is falls within the certificate start and end times, then the certificateValidFromDate and certificateExpiryDate parameters can be then passed to the validateCertificateTimes function.
All dates returned from this function are in UTC (number of seconds since 00:00:00 January 1 1970).
| certificate | The full path to the certificate file to validate. |
| certificateValidFromDate | If the certificate file can be read, this field will be populated with the date from which certificate this certificate is valid. |
| certificateExpiryDate | If the certificate file can be read, this field will be populated with the expiry date of the certificate. |
| certificateIssuer | This string, if provided, will be populated with the X500 keys contained within the files. The data within the string will be comma separated with fields in the form of <Two character key code>=<data>. |
| bool TSLS63MediaIngestManager::queryDataServer | ( | unsigned int | index, |
| TSLSimpleString & | dataServerID ) |
Query the data server for the given index.
This method may be used in conjunction with queryCellPermit to iterate through all the loaded cell permits.
| index | The index of the data server to query |
| dataServerID | Storage for the returned data server ID |
| bool TSLS63MediaIngestManager::removeCellPermit | ( | const char * | dataServerID, |
| const char * | cellName ) |
Remove a cell permit from the media ingest manager, for the given data server
| dataServerID | The ID of the data server |
| cellName | The cell name of the permit |
| bool TSLS63MediaIngestManager::removeDataServer | ( | const char * | dataServerID | ) |
Remove all cell permits from the media ingest manager, for the given data server
| dataServerID | The ID of the data server. |
| void TSLS63MediaIngestManager::setProcessingFlags | ( | TSLFilterProcess | processingFlags | ) |
Allows the processing options when reading S57 data to be set.
The following option increases the time to ingest data but improves performance of drawing:
TSLFilterProcessKeyHoling | TSLFilterProcessIgnorePolygonGeometryFailures
|
static |
This method checks that a query time falls between a start and end time provided. This function is intended to be used after calling the queryCertificate function to retrieve the start and end times that a X509 certificate to valid from and to.
| validateTime | The time to test |
| validFromTime | The earliest time that is valid |
| expiryTime | The latest time that is valid |
