TreDef - mdaus/nitro GitHub Wiki
TRE objects represent the Tagged Record Extensions found within a NITF file. They contain Fields which can be added, removed, retrieved or set. TREs provided the basic capability for extending NITF files. TREs may be present in any of the headers and subheaders found in the NITF.
The TRE manages access to parsed data handled by its associated plug-in. If no suitable plug-in is found, the default handler will be used. It is up to the plug-in to handle how this data is stored, but currently the default implementation for most of the plug-ins uses a hash table internally.
If you want to define your own TRE plug-in you simply have to fulfill the Handler interface. Copied below are the methods and documentation from the header file containing the definitions.
/*============================================================================*/
/*===========================BEGIN TRE HANDLER API============================*/
/*============================================================================*/
/*!
* The plug-in is allowed to do some initialization to prepare the TRE
* \param tre The TRE to initialize
* \param id An optional ID used to further specify a specific version, etc.
* \param error The error object
* \return NITF_FAILURE if an error occurred, otherwise NITF_SUCCESS
*/
typedef NITF_BOOL (*NITF_TRE_INIT) (nitf_TRE* tre,
const char* id,
nitf_Error * error);
/*!
* Read data from the given IOHandle, parsing it however the plug-in desires.
* \param io The IOHandle we are reading from
* \param length The length of the TRE (i.e. # of bytes to read)
* \param tre The associated TRE
* \param record The associated Record object
* \param error The error object
* \return NITF_FAILURE if an error occurred, otherwise NITF_SUCCESS
*/
typedef NITF_BOOL (*NITF_TRE_READER)(nitf_IOHandle io,
nitf_Uint32 length,
nitf_TRE *tre,
struct _nitf_Record *record,
nitf_Error *error);
/*!
* Returns a nitf_List* of Fields that match the input XPath-like pattern.
* \param tre The associated TRE
* \param pattern The XPath pattern used to search for fields
* \param error The error object
* \return nitf_List* of fields, or NULL if an error occurred
*/
typedef nitf_List* (*NITF_TRE_FIND)(nitf_TRE * tre,
const char *pattern,
nitf_Error* error);
/*!
* Sets a field in the given TRE. It is up to the plug-in to
* \param tre The associated TRE
* \param tag The name of the field
* \param data The data (void*) to set the field to
* \param dataLength The size of the data
* \param error The error object
* \return NITF_FAILURE if an error occurred, otherwise NITF_SUCCESS
*/
typedef NITF_BOOL (*NITF_TRE_FIELD_SET)(nitf_TRE * tre,
const char *tag,
NITF_DATA * data,
size_t dataLength,
nitf_Error * error);
/*!
* Returns the one Field with the given tag ID
* \param tre The associated TRE
* \param tag The tag, or name of the field to return
* \return the nitf_Field*, or NULL if it doesn't exist (or error)
*/
typedef nitf_Field* (*NITF_TRE_FIELD_GET)(nitf_TRE * tre,
const char *tag);
/*!
* Sets a field in the given TRE. It is up to the plug-in to
* \param io The IOHandle to write to
* \param tre The associated TRE to write
* \param record The associated Record object
* \param error The error object
* \return NITF_FAILURE if an error occurred, otherwise NITF_SUCCESS
*/
typedef NITF_BOOL (*NITF_TRE_WRITER)(nitf_IOHandle io,
nitf_TRE* tre,
struct _nitf_Record* record,
nitf_Error *error);
/*!
* Returns the current size of the TRE.
* \param tre The associated TRE
* \param error The error object
* \return The size of the TRE, or -1 if an error occurred
*/
typedef int (*NITF_TRE_SIZE)(nitf_TRE *tre, nitf_Error *error);
/*!
* Sets a field in the given TRE. It is up to the plug-in to
* \param source The source TRE to clone
* \param dest The destination TRE, where the source will be cloned to
* \param error The error object
* \return NITF_FAILURE if an error occurred, otherwise NITF_SUCCESS
*/
typedef NITF_BOOL (*NITF_TRE_CLONE)(nitf_TRE *source,
nitf_TRE *dest,
nitf_Error *error);
/*!
* Destroy any internal data associated with the given TRE. You should not
* destroy the TRE. It will be deleted by the library.
* \param tre The associated TRE
*/
typedef void (*NITF_TRE_DESTRUCT)(nitf_TRE*);
/*!
* Returns a nitf_TREEnumerator for the TRE
* \param tre The associated TRE
* \param error The error object
* \return an enumerator, or NULL if an error occurred
*/
typedef nitf_TREEnumerator* (*NITF_TRE_ITERATOR)(nitf_TRE *tre,
nitf_Error *error);
/*!
* \brief The TRE Handler Interface
*
* This interface should be fulfilled by any plug-in that wants to handle a TRE.
* View the documentation above for each of the methods below.
* In addition to the methods, there is an optional data field (of type
* NITF_DATA*) which allows the plug-in to store data associated with the
* Handler.
*
*/
typedef struct _nitf_TREHandler
{
/* The init method gets called when creating a TRE from scratch */
NITF_TRE_INIT init;
/* The read method gets called when reading a TRE from an IOHandle */
NITF_TRE_READER read;
/* setField is called by the setField proxy of the TRE API */
NITF_TRE_FIELD_SET setField;
/* getField is called by the getField proxy of the TRE API */
NITF_TRE_FIELD_GET getField;
/* find is called by the find proxy of the TRE API */
NITF_TRE_FIND find;
/* write gets called when writing the TRE to an output IOHandle */
NITF_TRE_WRITER write;
/* begin is called by the begin proxy of the TRE API */
NITF_TRE_ITERATOR begin;
/* getCurrentSize is called by the getCurrentSize proxy of the TRE API */
NITF_TRE_SIZE getCurrentSize;
/* clone is called when a TRE is cloned */
NITF_TRE_CLONE clone;
/*
* destruct is called when a TRE is destroyed - NOT when the handler is.
* destruct is an optional operation and doesn't need to be provided by
* plug-in implementations
*/
NITF_TRE_DESTRUCT destruct;
/* optional data that contains handler-wide data for supporting TREs of
* the type that the plug-in handles
*/
NITF_DATA* data;
} nitf_TREHandler;
/*============================================================================*/
/*===========================END TRE HANDLER API==============================*/
/*============================================================================*/
/*===========================BEGIN TRE HANDLER API============================*/
/*============================================================================*/
/*!
* The plug-in is allowed to do some initialization to prepare the TRE
* \param tre The TRE to initialize
* \param id An optional ID used to further specify a specific version, etc.
* \param error The error object
* \return NITF_FAILURE if an error occurred, otherwise NITF_SUCCESS
*/
typedef NITF_BOOL (*NITF_TRE_INIT) (nitf_TRE* tre,
const char* id,
nitf_Error * error);
/*!
* Read data from the given IOHandle, parsing it however the plug-in desires.
* \param io The IOHandle we are reading from
* \param length The length of the TRE (i.e. # of bytes to read)
* \param tre The associated TRE
* \param record The associated Record object
* \param error The error object
* \return NITF_FAILURE if an error occurred, otherwise NITF_SUCCESS
*/
typedef NITF_BOOL (*NITF_TRE_READER)(nitf_IOHandle io,
nitf_Uint32 length,
nitf_TRE *tre,
struct _nitf_Record *record,
nitf_Error *error);
/*!
* Returns a nitf_List* of Fields that match the input XPath-like pattern.
* \param tre The associated TRE
* \param pattern The XPath pattern used to search for fields
* \param error The error object
* \return nitf_List* of fields, or NULL if an error occurred
*/
typedef nitf_List* (*NITF_TRE_FIND)(nitf_TRE * tre,
const char *pattern,
nitf_Error* error);
/*!
* Sets a field in the given TRE. It is up to the plug-in to
* \param tre The associated TRE
* \param tag The name of the field
* \param data The data (void*) to set the field to
* \param dataLength The size of the data
* \param error The error object
* \return NITF_FAILURE if an error occurred, otherwise NITF_SUCCESS
*/
typedef NITF_BOOL (*NITF_TRE_FIELD_SET)(nitf_TRE * tre,
const char *tag,
NITF_DATA * data,
size_t dataLength,
nitf_Error * error);
/*!
* Returns the one Field with the given tag ID
* \param tre The associated TRE
* \param tag The tag, or name of the field to return
* \return the nitf_Field*, or NULL if it doesn't exist (or error)
*/
typedef nitf_Field* (*NITF_TRE_FIELD_GET)(nitf_TRE * tre,
const char *tag);
/*!
* Sets a field in the given TRE. It is up to the plug-in to
* \param io The IOHandle to write to
* \param tre The associated TRE to write
* \param record The associated Record object
* \param error The error object
* \return NITF_FAILURE if an error occurred, otherwise NITF_SUCCESS
*/
typedef NITF_BOOL (*NITF_TRE_WRITER)(nitf_IOHandle io,
nitf_TRE* tre,
struct _nitf_Record* record,
nitf_Error *error);
/*!
* Returns the current size of the TRE.
* \param tre The associated TRE
* \param error The error object
* \return The size of the TRE, or -1 if an error occurred
*/
typedef int (*NITF_TRE_SIZE)(nitf_TRE *tre, nitf_Error *error);
/*!
* Sets a field in the given TRE. It is up to the plug-in to
* \param source The source TRE to clone
* \param dest The destination TRE, where the source will be cloned to
* \param error The error object
* \return NITF_FAILURE if an error occurred, otherwise NITF_SUCCESS
*/
typedef NITF_BOOL (*NITF_TRE_CLONE)(nitf_TRE *source,
nitf_TRE *dest,
nitf_Error *error);
/*!
* Destroy any internal data associated with the given TRE. You should not
* destroy the TRE. It will be deleted by the library.
* \param tre The associated TRE
*/
typedef void (*NITF_TRE_DESTRUCT)(nitf_TRE*);
/*!
* Returns a nitf_TREEnumerator for the TRE
* \param tre The associated TRE
* \param error The error object
* \return an enumerator, or NULL if an error occurred
*/
typedef nitf_TREEnumerator* (*NITF_TRE_ITERATOR)(nitf_TRE *tre,
nitf_Error *error);
/*!
* \brief The TRE Handler Interface
*
* This interface should be fulfilled by any plug-in that wants to handle a TRE.
* View the documentation above for each of the methods below.
* In addition to the methods, there is an optional data field (of type
* NITF_DATA*) which allows the plug-in to store data associated with the
* Handler.
*
*/
typedef struct _nitf_TREHandler
{
/* The init method gets called when creating a TRE from scratch */
NITF_TRE_INIT init;
/* The read method gets called when reading a TRE from an IOHandle */
NITF_TRE_READER read;
/* setField is called by the setField proxy of the TRE API */
NITF_TRE_FIELD_SET setField;
/* getField is called by the getField proxy of the TRE API */
NITF_TRE_FIELD_GET getField;
/* find is called by the find proxy of the TRE API */
NITF_TRE_FIND find;
/* write gets called when writing the TRE to an output IOHandle */
NITF_TRE_WRITER write;
/* begin is called by the begin proxy of the TRE API */
NITF_TRE_ITERATOR begin;
/* getCurrentSize is called by the getCurrentSize proxy of the TRE API */
NITF_TRE_SIZE getCurrentSize;
/* clone is called when a TRE is cloned */
NITF_TRE_CLONE clone;
/*
* destruct is called when a TRE is destroyed - NOT when the handler is.
* destruct is an optional operation and doesn't need to be provided by
* plug-in implementations
*/
NITF_TRE_DESTRUCT destruct;
/* optional data that contains handler-wide data for supporting TREs of
* the type that the plug-in handles
*/
NITF_DATA* data;
} nitf_TREHandler;
/*============================================================================*/
/*===========================END TRE HANDLER API==============================*/
/*============================================================================*/