TSLDataHandler Class Reference

Detailed Description

Handles the retrieval of externally held data for TSLDataSets and stores human-readable names, types, lengths and precision of fields.

The object holds a series of lookup tables, one per feature ID that it is aware of. The lookup tables map the 2 character field key to a human readable field name, a type and a length. Thus this class allows the user to discover the human-readable field name and 'desired' field type, field length and field precision given a feature ID and field key.

Public Member Functions
const char *	addFieldDefinition (TSLFeatureID featureID, const TSLFieldDefinition *fieldDefinition)
const char *	availableField (TSLFeatureID featureID, int index) const
const char *	availableKey (TSLFeatureID featureID, int index) const
bool	copyFieldDefinitions (const TSLDataHandler *dataHandler, TSLFeatureID featureID)
const char *	findKey (const char *fieldName, TSLFeatureID featureID) const
const char *	findName (const char *fieldKey, TSLFeatureID featureID) const
const TSLFieldDefinition *	getFieldDefinition (const char *fieldKey, TSLFeatureID featureID) const
int	numAvailableFields (TSLFeatureID featureID) const
int	numAvailableKeys (TSLFeatureID featureID) const
bool	removeField (const char *fieldKey, TSLFeatureID featureID)

Member Function Documentation

addFieldDefinition()

const char * TSLDataHandler::addFieldDefinition	(	TSLFeatureID	featureID,
		const TSLFieldDefinition *	fieldDefinition )

Add a new field definition to the handler.

Parameters

featureID	the feature ID to add this field definition for.
fieldDefinition	a TSLFieldDefinition object which has been populated with all the information required to be stored in the handler. If no field key has been specified, the key will be automatically generated.

Returns

the field key if the field has been successfully added, 0 if the key already exists within the scope of the feature ID.

availableField()

const char * TSLDataHandler::availableField	(	TSLFeatureID	featureID,
		int	index ) const

Returns a pointer to the human-readable name for the given index. Use in conjunction with numAvailableFields() to iterate through the field names.

Parameters

featureID	the feature ID.
index	the given index.

Returns

pointer to the field name, 0 on error. This pointer points to internal data and must not be freed.

Note

it is possible for a TSLDataSet to contain data which does not have a human readable field name.

availableKey()

const char * TSLDataHandler::availableKey	(	TSLFeatureID	featureID,
		int	index ) const

Returns a pointer to the 2-character field key for the given index. Use in conjunction with numAvailableKeys() to iterate through the field keys.

Parameters

featureID	the feature ID.
index	the given index.

Returns

pointer to the field key, 0 on error. This pointer points to internal data and must not be freed.

copyFieldDefinitions()

bool TSLDataHandler::copyFieldDefinitions	(	const TSLDataHandler *	dataHandler,
		TSLFeatureID	featureID )

Copies all field definitions for the specified featureID to this Data Handler

Parameters

dataHandler	Source data handler to copy field definitions from
featureID	Feature ID to copy field definitions for, -1 copies all fields in all features.

Returns

true if successfully copied, false otherwise.

findKey()

const char * TSLDataHandler::findKey	(	const char *	fieldName,
		TSLFeatureID	featureID ) const

Returns the field key which identifies data associated with the specified human-readable field name.

Parameters

fieldName	the human-readable field name.
featureID	the feature ID.

If the field name is not understood by the handler then the method will return 0.

findName()

const char * TSLDataHandler::findName	(	const char *	fieldKey,
		TSLFeatureID	featureID ) const

Returns the human-readable field name which identifies data associated with the specified key.

Parameters

fieldKey	the field key.
featureID	the feature ID.

If the field key is not understood by the handler then the method will return 0.

getFieldDefinition()

const TSLFieldDefinition * TSLDataHandler::getFieldDefinition	(	const char *	fieldKey,
		TSLFeatureID	featureID ) const

Get an existing field definition from the handler.

Parameters

fieldKey	a 2 character code which uniquely identifies this field within the scope of the specified featureID.
featureID	the feature ID to add this field definition for.

Returns

a populated TSLFieldDefinition object on success, NULL otherwise.

Note also that specifying a type and length here does not imply that all TSLVariant objects using this key will be of the same type and length. Rather, in most instances the type and length specified here should be considered to be the 'proper' or 'desired' type and length of the field. Individual records may have a different type.

numAvailableFields()

int TSLDataHandler::numAvailableFields

(

TSLFeatureID

featureID

)

const

Returns the number of fields defined for the given feature ID.

Parameters

featureID

the feature ID.

Equivalent to 'numAvailableKeys'.

numAvailableKeys()

int TSLDataHandler::numAvailableKeys

(

TSLFeatureID

featureID

)

const

Returns the number of keys defined for the given feature ID.

Parameters

featureID

the feature ID.

Equivalent to 'numAvailableFields'.

removeField()

bool TSLDataHandler::removeField	(	const char *	fieldKey,
		TSLFeatureID	featureID )

Removes a field definition from the handler.

Parameters

featureID	the feature ID to remove this field definition from.
fieldKey	a 2 character code which uniquely identifies the field to be removed within the scope of the specified featureID.

Returns

true if the field has been successfully removed, false if the key is not found within the scope of the feature ID.