Nitf::TreParserShell Class Reference
[Plug-In Shells]

This class is a shell for a tre parer plug-in. More...

#include <NitfTreParserShell.h>

Inheritance diagram for Nitf::TreParserShell:

List of all members.

Public Member Functions
	TreParserShell ()
	~TreParserShell ()
std::string	getShortDescription () const
bool	runOperationalTests (Progress *pProgress, std::ostream &failure)
TreState	isTreValid (const DynamicObject &tre, std::ostream &reporter) const
bool	ossimTagToDynamicObject (const ossimNitfRegisteredTag &input, DynamicObject &output, std::string &errorMessage) const
bool	toDynamicObject (std::istream &input, size_t numBytes, DynamicObject &output, std::string &errorMessage) const
bool	ossimTagFromDynamicObject (const DynamicObject &input, ossimNitfRegisteredTag &tre, std::string &errorMessage) const
bool	fromDynamicObject (const DynamicObject &input, std::ostream &output, size_t &numBytesWritten, std::string &errorMessage) const
bool	importMetadata (const DynamicObject &tre, RasterDataDescriptor &descriptor, std::string &errorMessage) const
TreExportStatus	exportMetadata (const RasterDataDescriptor &descriptor, const RasterFileDescriptor &exportDescriptor, DynamicObject &tre, unsigned int &ownerIndex, std::string &tagType, std::string &errorMessage) const

---

Detailed Description

This class is a shell for a tre parer plug-in.

TreParser developers should take this class and extend it to support their importer specific code.

Definition at line 27 of file NitfTreParserShell.h.

---

Constructor & Destructor Documentation

Nitf::TreParserShell::TreParserShell

(

)

Nitf::TreParserShell::~TreParserShell

(

)

---

Member Function Documentation

std::string Nitf::TreParserShell::getShortDescription

(

)

const [virtual]

Returns a short description for the plug-in.

This method returns a short 50-charater or less description about the plug-in. This short description is used for brief descriptive table entries in the GUI.

Returns:

The short plug-in description.

See also:

getDescription()

Default Implementation:

The default implementation returns a general description based on the results of getName().

Reimplemented from PlugInShell.

bool Nitf::TreParserShell::runOperationalTests	(	Progress *	pProgress,
		std::ostream &	failure
	)			[virtual]

Executes operational tests generically.

This method is used to run basic tests and to make sure the plug-in is operating properly. Running this method on all plug-ins can be used to relatively quickly determine if the application has been installed properly and all plug-ins are operational.

Parameters:

	pProgress	On input, pProgress provides an object for the plug-in to update the progress of the testing. This allows the application to update the user with a progress dialog and to show current status.
	failure	On output, failure is an output stream in which the plug-in can record detailed formatted text about what went wrong in with the test. This parameter should not be used to record general status information. Nothing should be logged to this stream unless the tests failed and false is returned from the method.

Returns:

Returns true if the operational tests executed successfully; otherwise returns false.

Default Implementation:

The default implementation returns true, since most TreParser plug-ins will not require operational tests.

Implements Testable.

TreState Nitf::TreParserShell::isTreValid	(	const DynamicObject &	tre,
		std::ostream &	reporter
	)			const [virtual]

Examine the TRE to determine if it is valid.

Parameters:

	tre	The TRE to examine.
	reporter	Write to this ostream with information regarding a TreState::SUSPECT or TreState::INVALID TRE.

Returns:

The TreState for the given TRE.

Default Implementation:

The default implementation returns TreState::UNTESTED.

Implements Nitf::TreParser.

bool Nitf::TreParserShell::ossimTagToDynamicObject	(	const ossimNitfRegisteredTag &	input,
		DynamicObject &	output,
		std::string &	errorMessage
	)			const [virtual]

Load the TRE directly from an ossimNitfRegisteredTag.

Implementers should implement either this function or toDynamicObject(std::istream&, size_t, DynamicObject&) const to load the TRE.

Parameters:

	input	The ossimNitfRegisteredTag to read from.
	output	The DynamicObject to write to.
	errorMessage	If this is modified by the function, it will be displayed to the user as a warning that imported TREs might be incomplete, missing, etc.

Warning:

This method may be called multiple times during the life of the object.

Returns:

True if the operation succeeded, false otherwise.

Default Implementation:

The default implementation returns false, so that developers only need to override those methods they wish to implement.

Implements Nitf::TreParser.

bool Nitf::TreParserShell::toDynamicObject	(	std::istream &	input,
		size_t	numBytes,
		DynamicObject &	output,
		std::string &	errorMessage
	)			const [virtual]

Load the TRE from an istream.

Implementers should implement either this function or ossimTagToDynamicObject(ossimNitfRegisteredTag&, DynamicObject&) const to load the TRE. This function will only be called if the other returned false.

Parameters:

	input	The istream to read from. The data within does not include the CETAG or CEL fields.
	numBytes	The number of bytes to read.
	output	The DynamicObject to write to.
	errorMessage	If this is modified by the function, it will be displayed to the user as a warning that imported TREs might be incomplete, missing, etc.

Warning:

This method may be called multiple times during the life of the object.

Returns:

True if the operation succeeded, false otherwise.

Default Implementation:

The default implementation returns false, so that developers only need to override those methods they wish to implement.

Implements Nitf::TreParser.

bool Nitf::TreParserShell::ossimTagFromDynamicObject	(	const DynamicObject &	input,
		ossimNitfRegisteredTag &	tre,
		std::string &	errorMessage
	)			const [virtual]

Write the TRE directly to an ossimNitfRegisteredTag.

Implementers should implement either this function or fromDynamicObject(const DynamicObject&, std::ostream&, size_t&) const to write the TRE.

Parameters:

	input	The DynamicObject to read from.
	tre	The ossimNitfRegisteredTag to write to.
	errorMessage	If this is modified by the function, it will be displayed to the user as a warning that exported TREs might be incomplete, missing, etc.

Warning:

This method may be called multiple times during the life of the object.

Returns:

True if the operation succeeded, false otherwise.

Default Implementation:

The default implementation returns false, so that developers only need to override those methods they wish to implement.

Implements Nitf::TreParser.

bool Nitf::TreParserShell::fromDynamicObject	(	const DynamicObject &	input,
		std::ostream &	output,
		size_t &	numBytesWritten,
		std::string &	errorMessage
	)			const [virtual]

Write the TRE from a DynamicObject into an ostream.

Implementers should implement either this function or ossimTagFromDynamicObject(const DynamicObject&, ossimNitfRegisteredTag&) const to write the TRE. This function will only be called if the other returned false.

Parameters:

	input	The DynamicObject to read from.
	output	The ostream to write to. Do not write the CETAG or CEL.
	numBytesWritten	The number of bytes written.
	errorMessage	If this is modified by the function, it will be displayed to the user as a warning that exported TREs might be incomplete, missing, etc.

Warning:

This method may be called multiple times during the life of the object.

Returns:

True if the operation succeeded, false otherwise.

Default Implementation:

The default implementation returns false, so that developers only need to override those methods they wish to implement.

Implements Nitf::TreParser.

bool Nitf::TreParserShell::importMetadata	(	const DynamicObject &	tre,
		RasterDataDescriptor &	descriptor,
		std::string &	errorMessage
	)			const [virtual]

Import contents of the TRE to specific fields within the descriptor.

For example, a TRE might contain wavelength data which would be appropriately represented in the Special Metadata.

Parameters:

	tre	The parsed TRE to place copies of data within the descriptor.
	descriptor	The descriptor to place copies of data within.
	errorMessage	If this is modified by the function, it will be displayed to the user as a warning that imported TREs might be incomplete, missing, etc.

Returns:

true if the operation successfully populated the descriptor, false otherwise. This method should return false if there is no need to import metadata into the descriptor.

Default Implementation:

The default implementation returns false, so that developers only need to override those methods they wish to implement.

Implements Nitf::TreParser.

TreExportStatus Nitf::TreParserShell::exportMetadata	(	const RasterDataDescriptor &	descriptor,
		const RasterFileDescriptor &	exportDescriptor,
		DynamicObject &	tre,
		unsigned int &	ownerIndex,
		std::string &	tagType,
		std::string &	errorMessage
	)			const [virtual]

Export contents descriptor into a tre.

For example, a TRE might contain wavelength data which would be appropriately represented in the Special Metadata.

This method can also be used to modify or create new TREs on export. This might be desired if the TRE must be modified when chipping, or to create a TRE for a dataset not initially loaded as a NITF.

Parameters:

	descriptor	The data descriptor to export from.
	exportDescriptor	The descriptor which specifies which portion is to be exported.
	tre	On return, this should contain the TRE to export with a future call to fromDynamicObject().
	ownerIndex	When returning TreExportStatus::REPLACE, specifies the index of the owner of this tag. This should be set to 0 for the file header and 1 for the image subheader. If this value is unspecified, it will default to the image subheader.
	tagType	When returning TreExportStatus::REPLACE, specifies the type of this tag. Valid values are "UDHD" "UDID", "XHD", and "IXSHD". If this value is unspecified, it will default to "IXSHD".
	errorMessage	If this is modified by the function, it will be displayed to the user as a warning that exported TREs might be incomplete, missing, etc.

Returns:

A TreExportStatus which indicates what to do with existing and created TREs that this parser handles.

See also:

CreateOnExportSubtype()

Default Implementation:

The default implementation returns UNCHANGED, so that developers only need to override those methods they wish to implement. Note that if a subclass wishes to reimplement this function, the subclass should use CreateOnExportSubtype().

Implements Nitf::TreParser.