Class CWFGM FuelMap. More...

#include <CWFGM_FuelMap.h>

Collaboration diagram for CCWFGM_FuelMap:

Public Member Functions
STDMETHOD()	MT_Lock (USHORT exclusive, USHORT obtain)

STDMETHOD()	IndexOfFuel (ICWFGM_Fuel fuel, long file_index, long export_file_index, UCHAR fuel_index)

STDMETHOD()	FuelAtFileIndex (long file_index, UCHAR fuel_index, long export_file_index, ICWFGM_Fuel **fuel)

STDMETHOD()	FuelAtIndex (UCHAR fuel_index, long file_index, long export_file_index, ICWFGM_Fuel **fuel)

STDMETHOD()	RemoveFuelIndex (ICWFGM_Fuel *fuel, long file_index)

STDMETHOD()	RemoveFuel (ICWFGM_Fuel *fuel)

STDMETHOD()	AddFuel (ICWFGM_Fuel fuel, long file_index, long export_file_index, UCHAR fuel_index)

STDMETHOD()	GetFuelCount (UCHAR count, UCHAR unique_count)

STDMETHOD()	Copy (ICWFGM_FuelMap *toCopy)

STDMETHOD()	Clone (ICWFGM_FuelMap **newFuelMap)

STDMETHOD()	GetAvailableFileIndex (long *index)

STDMETHOD()	GetAttribute (USHORT option, VARIANT *value)

STDMETHOD()	SetAttribute (USHORT option, VARIANT value)

STDMETHOD()	get_UserData (VARIANT *pVal)

STDMETHOD()	put_UserData (VARIANT newVal)

Public Member Functions inherited from ICWFGM_FuelMap
HRESULT	MT_Lock ([in] unsigned short exclusive, [in] unsigned short obtain)

HRESULT	Copy ([in]ICWFGM_FuelMap *toCopy)

HRESULT	Clone ([out]ICWFGM_FuelMap **newFuelMap)

HRESULT	GetFuelCount ([out]unsigned char count, [out, retval]unsigned char unique_count)

HRESULT	AddFuel ([in]ICWFGM_Fuel fuel, [in]long file_index, [in]long export_file_index, [out, retval]unsigned char fuel_index)

HRESULT	RemoveFuel ([in]ICWFGM_Fuel *fuel)

HRESULT	FuelAtIndex ([in]unsigned char fuel_index, [out]long file_index, [out]long export_file_index, [out, retval]ICWFGM_Fuel **fuel)

HRESULT	FuelAtFileIndex ([in]long file_index, [out]unsigned char fuel_index, [out]long export_file_index, [out, retval]ICWFGM_Fuel **fuel)

HRESULT	IndexOfFuel ([in]ICWFGM_Fuel fuel, [out]long file_index, [out]long export_file_index, [in, out]unsigned char fuel_index)

HRESULT	RemoveFuelIndex ([in]ICWFGM_Fuel *fuel, [in]long file_index)

HRESULT	GetAvailableFileIndex ([out]long *index)

HRESULT	GetAttribute ([in]unsigned short option, [out, retval]VARIANT *value)

HRESULT	SetAttribute ([in]unsigned short option, [in]VARIANT value)

Additional Inherited Members
Properties inherited from ICWFGM_FuelMap
VARIANT	UserData `[get, set]`

Detailed Description

Class CWFGM FuelMap.

A CWFGM FuelMap retains relationships between CWFGM fuels and their associated grid file and internal indices. The grid file indices are predetermined when the files are exported from the GIS. The FuelMap object assigns but may not change internal indexes. The FuelMap may retain up to 255 unique relationships. This object also implements the standard COM IPersistStream, IPersistStreamInit, and IPersisStorage interfaces, for use for loading and saving. Serialization methods declared in these interfaces save the associations as well as the fuel types. The client application must be careful not to save a fuel type twice if it maintains its own list of fuel types. This rule is imposed to remove any unnecessary dependencies on the client code to ensure correctness of operation. The client application must also be aware and compensate for any composite (mixed) fuel types, too.

Member Function Documentation

STDMETHODIMP CCWFGM_FuelMap::AddFuel	(	ICWFGM_Fuel *	fuel,
		long	file_index,
		long	export_file_index,
		UCHAR *	fuel_index
	)

Adds a relationship between a CWFGM fuel and a grid file index, sets 'fuel_index' to the internal index that this FuelMap has assigned to it. This call will increment the COM reference counter associated with 'fuel'.

Parameters

fuel	Fuel to add.
file_index	Index for the fuel during grid import operations.
export_file_index	Index for the fuel during grid export operations. This value is currently unused by this object and is available for any purposes that the client application may have.
fuel_index	Return value for internal fuel index.

See Also: ICWFGM_FuelMap::AddFuel

Return values

E_POINTER	The address provided for fuel or fuel_index is invalid.
ERROR_SCENARIO_SIMULATION_RUNNING	Value cannot be changed as it is being used in a currently running scenario.
E_NOINTERFACE	'fuel' does not support the ICWFGM_Fuel interface.
ERROR_NOT_ENOUGH_MEMORY	Insufficient memory. 255 Fuel entries currently exist.
ERROR_FUELS_GRIDVALUE_ALREADY_ASSIGNED	The fuel to add would have been assigned a non-unique file identifier that is not (-1).
SUCCESS_FUELS_FUEL_ALREADY_ADDED	The fuel is already in the
FuelMap;	a particular fuel can occur in a FuelMap more than once.
S_OK	Successful.

STDMETHODIMP CCWFGM_FuelMap::Clone ( ICWFGM_FuelMap ** newFuelMap )

Creates a new fuel map and places the pointer to the object in 'newFuelMap'. Duplicates all relationships maintained by the object being called in a new FuelMap object. This call differs from 'Copy' in that all fuel types are also duplicated.

Parameters

newFuelMap Receiver pointer for the newly created, cloned fuel map object.

See Also: ICWFGM_FuelMap::Clone

Return values

E_POINTER	The address provided for newFuelMap is invalid.
E-OUTOFMEMORY	Insufficient memory.
E_NOINTERFACE	'newFuelMap' is not a successfully created CWFGM FuelMap object.
ERROR_SEVERITY_WARNING	A file exception or other miscellaneous error.
S_OK	Successful.

STDMETHODIMP CCWFGM_FuelMap::Copy ( ICWFGM_FuelMap * toCopy )

Copy()'s semantics are different from Clone()'s: Copy() only copies the handles to fuel types, it doesn't make copies of the fuel types. If you want a complete standalone copy of everything including copies of the fuel types,then use Clone().

Parameters

toCopy Handle of fuel type.

See Also: ICWFGM_FuelMap::Copy

Return values

E_POINTER	The address provided is invalid.
E_NOINTERFACE	Interface not supported.
S_OK	Successful.

STDMETHODIMP CCWFGM_FuelMap::FuelAtFileIndex	(	long	file_index,
		UCHAR *	fuel_index,
		long *	export_file_index,
		ICWFGM_Fuel **	fuel
	)

Given a grid file index, sets 'fuel_index' to the internal index,'export_file_index' to the export grid file index, and sets 'fuel' to the appropriate CWFGM Fuel interface handle. This call does not adjust the COM reference counters for 'fuel'; if the caller plans on retaining the pointer then it should increment the reference counter.

Parameters

file_index	A grid file index.
fuel_index	Return value for an internal fuel index.
export_file_index	Return value for a grid file export index.
fuel	Return value for a CWFGM Fuel interface handle.

See Also: ICWFGM_FuelMap::FuelAtFileIndex

Return values

E_POINTER	The address provided for fuel_index or fuel is invalid.
S_OK	Successful.
ERROR_FUELS_FUEL_UNKNOWN	'file_index' is not in any associations.

STDMETHODIMP CCWFGM_FuelMap::FuelAtIndex	(	UCHAR	fuel_index,
		long *	file_index,
		long *	export_file_index,
		ICWFGM_Fuel **	fuel
	)

Given an internal fuel index, sets 'file_index' to the grid file import index, 'export_file_index' to the grid file export index, and sets 'fuel' to the appropriate CWFGM Fuel interface handle. This call does not adjust the COM reference counters for 'fuel'; if the caller plans on retaining the pointer then it should increment the reference counter.

Parameters

fuel_index	Internal fuel index.
file_index	Return value for a grid file import index.
export_file_index	Return value for a grid file export index.
fuel	Return value for a CWFGM Fuel interface handle.

See Also: ICWFGM_FuelMap::FuelAtIndex

Return values

E_POINTER	The address provided for file_index, export_file_index or fuel is invalid.
S_OK	Successful.
ERROR_FUELS_FUEL_UNKNOWN	'fuel_index' is invalid (currently unused).

STDMETHODIMP CCWFGM_FuelMap::get_UserData ( VARIANT * pVal )

This property is unused by this object, and is available for exclusive use by the client code. It is a VARIANT value to ensure that the client code can store a pointer value (if it chooses) for use in manual subclassing this object. This value is not loaded or saved during serialization operations, and it is the responsibility of the client code to manage any value or object stored here. Access to this property is not thread-safe.

Parameters

pVal	Value of UserData

See Also: ICWFGM_FuelMap::UserData

Return values

E_POINTER	The address provided for pVal is invalid
S_OK	Successful

STDMETHODIMP CCWFGM_FuelMap::GetAttribute	(	USHORT	option,
		VARIANT *	value
	)

Polymorphic. This routine retrieves an attribute/option value given the attribute/option index.

Parameters

option	Currently the only valid attribute/option index supported is CWFGM_ATTRIBUTE_LOAD_WARNING.
value	Return value for the attribute/option index.

See Also: ICWFGM_FuelMap::GetAttribute

Return values

E_POINTER	The address provided is invalid.
S_OK	Successful.
E_INVALIDARG	Unknown attribute/option index.

STDMETHODIMP CCWFGM_FuelMap::GetAvailableFileIndex ( long * index )

Returns an available file index. The logic is as follows: ignore (-9999) while searching all fuel mappings for the minimum negative import fuel index value. If no negative indicies exist, then return -2. Otherwise, return 1 less than the minimum found value.

Parameters

index Return value for a file index.

See Also: ICWFGM_FuelMap::GetAvailableFileIndex

Return values

E_POINTER	The address provided for index is invalid.
S_OK	Successful.

STDMETHODIMP CCWFGM_FuelMap::GetFuelCount	(	UCHAR *	count,
		UCHAR *	unique_count
	)

Sets 'count' to the number of fuel relationships currently in this FuelMap. Sets 'unique_count' to the number of fuels in this FuelMap.

Parameters

count	Return value for number of fuel relationships.
unique_count	Return value for number of fuels.

See Also: ICWFGM_FuelMap::GetFuelCount

Return values

E_POINTER	The address provided for count or unique_count is invalid.
S_OK	Successful.

STDMETHODIMP CCWFGM_FuelMap::IndexOfFuel	(	ICWFGM_Fuel *	fuel,
		long *	file_index,
		long *	export_file_index,
		UCHAR *	fuel_index
	)

Given a fuel interface, sets 'file_index' to the grid file import index, 'export_file_index' to the grid file export index, and sets 'fuel_index' to the internal index. This method can be called repeatedly to iterate through all relationships for a given fuel. The first call to this method should place (UCHAR)-1 into 'fuel_index' (always). Subsequent calls should use the previously returned 'fuel_index' value.

Parameters

fuel	A CWFGM Fuel interface handle.
file_index	Return value for a grid file import index.
export_file_index	Return value for a grid file export index.
fuel_index	Return value for an internal fuel index.

See Also: ICWFGM_FuelMap::IndexOfFuel

Return values

E_POINTER	The address provided for fuel, file_index or fuel_index is invalid.
S_OK	Successful.
ERROR_FUELS_FUEL_UNKNOWN	'file_index' is not in any associations.

STDMETHODIMP CCWFGM_FuelMap::MT_Lock	(	USHORT	exclusive,
		USHORT	obtain
	)

Changes the state of the object with respect to access rights. When the object is used by an active simulation, it must not be modified. When the object is somehow modified, it must be done so in an atomic action to prevent concerns with arising from multithreading. Note that these locks are primarily needed to ensure a simulation dependency is not changed while it occurs. Locking request is forwarded to each attached ICWFGM_Fuel object.

In the event of an error, then locking is undone to reflect an error state.

Parameters

exclusive	TRUE if the requester wants a write lock, false for read/shared access
obtain	TRUE to obtain the lock, FALSE to release the lock. If this is FALSE, then the 'exclusive' parameter must match the initial call used to obtain the lock.

See Also: ICWFGM_FuelMap::MT_Lock; ICWFGM_Fuel::MT_Lock

Return values

SUCCESS_STATE_OBJECT_UNLOCKED	Lock was released.
SUCCESS_STATE_OBJECT_LOCKED_WRITE	Exclusive/write lock obtained.
SUCCESS_STATE_OBJECT_LOCKED_SCENARIO	A scenario successfully required a lock for purposes of simulating.
SUCCESS_STATE_OBJECT_LOCKED_READ	Shared/read lock obtained.
S_OK	Successful

STDMETHODIMP CCWFGM_FuelMap::put_UserData ( VARIANT newVal )

This property is unused by this object, and is available for exclusive use by the client code. It is a VARIANT value to ensure that the client code can store a pointer value (if it chooses) for use in manual subclassing this object. This value is not loaded or saved during serialization operations, and it is the responsibility of the client code to manage any value or object stored here. Access to this property is not thread-safe.

Parameters

newVal Replacement value for UserData

See Also: ICWFGM_FuelMap::UserData

Return values

S_OK	Successful

STDMETHODIMP CCWFGM_FuelMap::RemoveFuel ( ICWFGM_Fuel * fuel )

Removes a given CWFGM fuel from this FuelMap. Removes all mappings related to this fuel object. This call will decrement the COM reference counter associated with 'fuel' for each index that is assigned to the fuel.

Parameters

fuel	Fuel to remove.

See Also: ICWFGM_FuelMap::RemoveFuel

Return values

E_POINTER	The address provided for fuel is invalid.
ERROR_SCENARIO_SIMULATION_RUNNING	Value cannot be changed as it is being used in a currently running scenario.
S_OK	Successful.
ERROR_FUELS_FUEL_UNKNOWN	'fuel' is not in the FuelMap.

STDMETHODIMP CCWFGM_FuelMap::RemoveFuelIndex	(	ICWFGM_Fuel *	fuel,
		long	file_index
	)

Removes the association between the file index for a given fuel. The call will also decrement the COM reference counter associated with the fuel, which will conditionally trigger deletion of the fuel.

Parameters

fuel	Fuel to remove relationship for.
file_index	File index to remove relationship for.

See Also: ICWFGM_FuelMap::RemoveFuelIndex

Return values

E_POINTER	The address provided for fuel is invalid.
ERROR_SCENARIO_SIMULATION_RUNNING	Value cannot be changed as it is used by a currently running scenario.
S_OK	Successful.
ERROR_FUELS_FUEL_UNKNOWN	The fuel/index association to be removed could not be found.

STDMETHODIMP CCWFGM_FuelMap::SetAttribute	(	USHORT	option,
		VARIANT	value
	)

Polymorphic. This routine sets an attribute/option value given the attribute/option index. Currently does not perform any operation and is simply reserved for future functionality.

Parameters

option	Reserved for future functionality.
value	Value for the attribute/option index

See Also: ICWFGM_FuelMap::SetAttribute

Return values

E_NOTIMPL This function is reserved for future functionality.

COM Programmer Documentation

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation