Represents an ignition to simulate. More...

#include <CWFGM_Fire.h>

Collaboration diagram for CCWFGM_Ignition:

Public Member Functions
STDMETHOD()	GetIgnitionTime (ULONGLONG *pVal)

STDMETHOD()	SetIgnitionTime (ULONGLONG newVal)

STDMETHOD()	Clone (ICWFGM_Ignition **fire)

STDMETHOD()	MT_Lock (USHORT exclusive, USHORT obtain)

STDMETHOD()	get_UserData (VARIANT *pVal)

STDMETHOD()	put_UserData (VARIANT newVal)

STDMETHOD()	AddIgnition (USHORT ignition_type, SAFEARRAY xy_pairs, ULONG index)

STDMETHOD()	SetIgnition (ULONG index, USHORT ignition_type, SAFEARRAY *xy_pairs)

STDMETHOD()	SetIgnitionWKB (ULONG index, SAFEARRAY *wkb)

STDMETHOD()	ClearIgnition (ULONG index)

STDMETHOD()	GetIgnitionCount (ULONG *count)

STDMETHOD()	GetIgnitionType (ULONG index, USHORT *ignition_type)

STDMETHOD()	GetIgnitionSize (ULONG index, ULONG *ignition_size)

STDMETHOD()	GetIgnitionWKBSize (ULONG index, ULONGLONG *ignition_size)

STDMETHOD()	GetIgnition (ULONG index, USHORT ignition_type, ULONG ignition_size, SAFEARRAY **xy_pairs)

STDMETHOD()	GetIgnitionWKB (ULONG index, SAFEARRAY **wkb)

STDMETHOD()	ImportIgnition (ICWFGM_GridEngine engine, const BSTR file_name, SAFEARRAY permissible_drivers)

STDMETHOD()	ExportIgnition (ICWFGM_GridEngine *engine, const BSTR driver_name, const BSTR projection, const BSTR file_name)

STDMETHOD()	SetAttribute (USHORT option, VARIANT value)

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

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

HRESULT	Clone ([out, retval]ICWFGM_Ignition **fire)

HRESULT	GetIgnitionTime ([out, retval]unsigned __int64 *pVal)

HRESULT	SetIgnitionTime ([in]unsigned __int64 newVal)

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

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

HRESULT	AddIgnition ([in]unsigned short ignition_type, [in]SAFEARRAY(double) xy_pairs, [out, retval]unsigned long *index)

HRESULT	SetIgnition ([in]unsigned long index, [in]unsigned short ignition_type, [in]SAFEARRAY(double) xy_pairs)

HRESULT	SetIgnitionWKB ([in]unsigned long index, [in]SAFEARRAY(unsigned char) wkb)

HRESULT	ClearIgnition ([in]unsigned long index)

HRESULT	GetIgnitionCount ([out, retval]unsigned long *count)

HRESULT	GetIgnitionType ([in]unsigned long index, [out, retval]unsigned short *ignition_type)

HRESULT	GetIgnitionSize ([in]unsigned long index, [out, retval]unsigned long *size)

HRESULT	GetIgnition ([in]unsigned long index, [out]unsigned short ignition_type, [out]unsigned long size, [in, out]SAFEARRAY(double)*xy_pairs)

HRESULT	GetIgnitionWKBSize ([in]unsigned long index, [out, retval]unsigned long long *size)

HRESULT	GetIgnitionWKB ([in]unsigned long index, [in, out]SAFEARRAY(unsigned char)*wkb)

HRESULT	ImportIgnition ([in] ICWFGM_GridEngine *engine, [in] const BSTR file_path, [in] SAFEARRAY(BSTR) permissible_drivers)

HRESULT	ExportIgnition ([in] ICWFGM_GridEngine *engine, [in] const BSTR driver_name, [in] const BSTR projection, [in] const BSTR file_path)

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

Detailed Description

Represents an ignition to simulate.

This COM object stores values for each ignition. Attributes of an ignition that are not of concern to the simulation engine, such as its name or comments, are the responsibility of the user interface and do not appear on the COM interface. Similarly, the application's management of ignitions is of no concern of the simulation engine, and the fire collection does not define a COM interface. The client application (such as CWFGM) is expected to use object-oriented technologies such as class inheritance to add attributes that the simulation engine is not concerned with.

This object also implements the standard COM IPersistStream, IPersistStreamInit, and IPersistStorage interfaces, for use for loading and saving. These operations save only the start time and ignition location for a fire, no simulation data can be recorded.

Member Function Documentation

STDMETHODIMP CCWFGM_Ignition::AddIgnition	(	USHORT	ignition_type,
		SAFEARRAY *	xy_pairs,
		ULONG *	index
	)

Adds an ignition to this ignition object.

Parameters

ignition_type	Whether it's a point, line, or polygon ignition. Valid values are: `CWFGM_FIRE_IGNITION_POINT` `CWFGM_FIRE_IGNITION_LINE` `CWFGM_FIRE_IGNITION_POLYGON_OUT` `CWFGM_FIRE_IGNITION_POLYGON_IN`
xy_pairs	2D Array of coordinates
index	Index of the newly added sub-ignition

See Also: ICWFGM_Ignition::AddIgnition

Return values

S_OK	Successful
ERROR_FIRE_IGNITION_TYPE_UNKNOWN	An invalid ignition type has been specified
ERROR_SCENARIO_SIMULATION_RUNNING	If this function is run while the scenario is running
E_INVALIDARG	If the ignition size has been set to less than or equal to zero
ERROR_SCENARIO_FIRE_ALRADY_ADDED	The fire being added is already associated with this scenario
E_OUTOFMEMORY	Insufficient memory
E_POINTER	Address for xy_pairs is invalid

STDMETHODIMP CCWFGM_Ignition::ClearIgnition ( ULONG index )

This method clears the sub-ignition from this ignition set. If index = (unsigned long) -1, then all ignitions are cleared.

Parameters

index Index of the sub-ignition to remove

See Also: ICWFGM_Ignition::ClearIgnition

Return values

S_OK	Successful
ERROR_SCENARIO_SIMULATION_RUNNING	If the fire is attached to a running simulation
E_INVALIDARG	If there are no ignitions to clear

STDMETHODIMP CCWFGM_Ignition::Clone ( ICWFGM_Ignition ** fire )

Creates a new ignition object with all the same properties of the object being called, returns a handle to the new object in fire. This method does not attach the new fire to any scenarios that this object is attached to, nor does it simulate any fire growth to duplicate the calculated data that this object may have.

Parameters

fire	An ignition object

See Also: ICWFGM_Ignition::Clone

Return values

E_POINTER	The address provided for fire is invalid
S_OK	Successful

STDMETHODIMP CCWFGM_Ignition::ExportIgnition	(	ICWFGM_GridEngine *	gridEngine,
		const BSTR	driver_name,
		const BSTR	bprojection,
		const BSTR	file_path
	)

Exports the ignition to the specified file path.

Parameters

gridEngine	Needed to convert from grid units for storage
driver_name	Determines the file format (refer to GDAL documentation for supported formats)
bprojection	Projection file
file_path	Path/file of the vector data

See Also: ICWFGM_Ignition::ExportIgnition

Return values

E_POINTER	The address provided for gridEngine, driver_name, file_path, or projection is invalid
E_INVALIDARG	Unspecified error
S_FALSE	Unspecified error
S_OK	Successful
ERROR_SEVERITY_WARNING	Unspecified failure
ERROR_GRID_UNINITIALIZED	Specified grid is invalid or not provided

STDMETHODIMP CCWFGM_Ignition::get_UserData ( VARIANT * pVal )

This property is unused by the fire object, and is available for exclusive use by the client code.  It is a VARIANT so that the client code store pointer values

for use in 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_Ignition::UserData

Return values

E_POINTER	The address provided for pVal is invalid
S_OK	Successful

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

Polymorphic.  This routine retrieves an attribute/option value given the attribute/option index.
    \param option Supported / valid attribute/option index supported are:

CWFGM_ATTRIBUTE_LOAD_WARNING BSTR. Any warnings generated by the COM object when deserializating.

Parameters

value Return value for the attribute/option index

See Also: ICWFGM_Ignition::GetAttribute

Return values

E_POINTER	The address provided for value is invalid
E_INVALIDARG	No valid parameters
S_OK	Successful

STDMETHODIMP CCWFGM_Ignition::GetIgnition	(	ULONG	index,
		USHORT *	ignition_type,
		ULONG *	ignition_size,
		SAFEARRAY **	xy_pairs
	)

This method returns the indices of the specified polygon sub-ignition at the specified index. size is adjusted as necessary to return the number of array entries used.

Parameters

index	Index of sub-ignition
ignition_type	Point, line, or poly ignition. Valid values are: `CWFGM_FIRE_IGNITION_POINT` `CWFGM_FIRE_IGNITION_LINE` `CWFGM_FIRE_IGNITION_POLYGON_OUT` `CWFGM_FIRE_IGNITION_POLYGON_IN`
ignition_size	Size of array (number of valid elements in provided array)
xy_pairs	2D Array of coordinates

See Also: ICWFGM_Ignition::GetIgnition

Return values

E_POINTER	The address provided for size, ignition_type, or xy_pairs is invalid
E_INVALIDARG	If there are no ignitions to get type from
S_OK	Successful
E_OUTOFMEMORY	Insufficient memory

STDMETHODIMP CCWFGM_Ignition::GetIgnitionCount ( ULONG * count )

Returns the number of sub-ignitions associated with this ignition object.

Parameters

count Number of sub-ignitions

See Also: ICWFGM_Ignition::GetIgnitionCount

Return values

E_POINTER	The address provided for size is invalid
S_OK	Successful

STDMETHODIMP CCWFGM_Ignition::GetIgnitionSize	(	ULONG	index,
		ULONG *	ignition_size
	)

This method returns the number of vertices of the specified sub-ignition. Or, if -1 is provided for index, then the maxumum number of vertices found for any of the sub-ignitions defined is returned.

Parameters

index	Sub-ignition being queried, or -1 to query all sub-ignitions.
ignition_size	Return value

See Also: ICWFGM_Ignition::GetIgnitionSize

Return values

E_POINTER	The address provided for size is invalid
E_INVALIDARG	If there are no ignitions to get type from
S_OK	Successful

STDMETHODIMP CCWFGM_Ignition::GetIgnitionTime ( ULONGLONG * pVal )

This property identifies the start time (in GMT, count of seconds since Midnight January 1, 1600) for the fire. Local time is calculated from data provided by the grid engine attached to a given scenario. This value cannot be modified when the fire object is attached to a running simulation.

Parameters

pVal	Value of IgnitionTime

See Also: ICWFGM_Ignition::GetIgnitionTime

Return values

E_POINTER	The address provided for pVal is invalid
S_OK	Successful
ERROR_SCENARIO_SIMULATION_RUNNING	If trying to set a new start time when the fire is attached to a running simulation

STDMETHODIMP CCWFGM_Ignition::GetIgnitionType	(	ULONG	index,
		USHORT *	ignition_type
	)

Returns the type of ignition whether it be point, line, or polygon.

Parameters

index	Sub-ginition being queried
ignition_type	Return value. Valid values are: `CWFGM_FIRE_IGNITION_POINT` `CWFGM_FIRE_IGNITION_LINE` `CWFGM_FIRE_IGNITION_POLYGON_OUT` `CWFGM_FIRE_IGNITION_POLYGON_IN`

See Also: ICFWGM_Ignition::GetIgnitionTime

Return values

E_POINTER	The address provided for ignition_type is invalid
E_INVALIDARG	If there are no ignitions to get type from
S_OK	Successful

STDMETHODIMP CCWFGM_Ignition::GetIgnitionWKB	(	ULONG	index,
		SAFEARRAY **	wkb
	)

This method returns the Well Known Binary array of the sub-ignition at the specified index.

Parameters

index	Index of sub-ignition
wkb	Array used to hold the WKB array

See Also: CCWFGM_Ignition::GetIgnitionWKB

STDMETHODIMP CCWFGM_Ignition::GetIgnitionWKBSize	(	ULONG	index,
		ULONGLONG *	ignition_size
	)

This method returns the size of the WKB array that will be generated from the sub-ignition at the specified index.

Parameters

index	Index of sub-ignition
size	Size of array in bytes

See Also: CCWFGM_Ignition::GetIgnitionWKBSize

STDMETHODIMP CCWFGM_Ignition::ImportIgnition	(	ICWFGM_GridEngine *	gridEngine,
		const BSTR	file_path,
		SAFEARRAY *	permissible_drivers
	)

Imports an ignition from the file path specified.

Parameters

gridEngine	Needed to convert to grid units for storage
file_path	File to import
permissible_drivers	Array of drivers (known by GDAL) identifying the file types that are allowed to be imported.

See Also: ICWFGM_Ignition::ImportIgnition

Return values

E_POINTER	The address provided for gridEngine or file_path is invalid
E_INVALIDARG	Cannot understand file_path
S_FALSE	Unspecified failure
S_OK	Successul
ERROR_SEVERITY_WARNING	Unspecified failure
ERROR_GRID_UNINITIALIZED	Specified grid is invalid or not provided

STDMETHODIMP CCWFGM_Ignition::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. All routines are otherwise multi-thread safe.

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 to obtain the lock.

See Also: ICWFGM_Ignition::MT_Lock

Return values

S_OK	Successful
SUCCESS_STATE_OBJECT_LOCKED_WRITE	Exclusive/write lock obtained
SUCCESS_STATE_OBJECT_LOCKED_SCENARIO	A scenario has a lock for purposes of simulating (shared/read)
SUCCESS_STATE_OBJECT_LOCKED_READ	Shared/read lock obtained

STDMETHODIMP CCWFGM_Ignition::put_UserData ( VARIANT newVal )

This property is unused by the fire object, and is available for exclusive use by the client code.  It is a VARIANT so that the client code store pointer values

for use in 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_Ignition::UserData

Return values

S_OK	Successful

STDMETHODIMP CCWFGM_Ignition::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_Ignition::SetAttribute

Return values

E_NOTIMPL This function is reserved for future functionality.

STDMETHODIMP CCWFGM_Ignition::SetIgnition	(	ULONG	index,
		USHORT	ignition_type,
		SAFEARRAY *	xy_pairs
	)

This method sets the ignition for this fire. This data cannot be modified when the fire object is attached to a running simulation. ignition_size states the number of ignition points to follow. The array is specified as consecutive X, Y pairs. The array sizes are defined by 2*ignition_size. The units for x, y are in grid units, not in metres, etc.

Parameters

index	Where to insert this sub-ignition
ignition_type	Whether it's a point, line, or polygon ignition. Valid values are: `CWFGM_FIRE_IGNITION_POINT` `CWFGM_FIRE_IGNITION_LINE` `CWFGM_FIRE_IGNITION_POLYGON_OUT` `CWFGM_FIRE_IGNITION_POLYGON_IN`
xy_pairs	2D Array of coordinates

See Also: ICWFGM_Ignition::SetIgnition

Return values

E_POINTER	The address provided for xy_pairs is invalid
S_OK	Successful
E_OUTOFMEMORY
ERROR_SCENARIO_SIMULATION_RUNNING	If the fire is attached to a running simulation
E_INVALIDARG	If any of the x or y values appear to be invalid

STDMETHODIMP CCWFGM_Ignition::SetIgnitionTime ( ULONGLONG newVal )

This property identifies the start time (in GMT, count of seconds since Midnight January 1, 1600) for the fire. Local time is calculated from data provided by the grid engine attached to a given scenario. This value cannot be modified when the fire object is attached to a running simulation.

Parameters

newVal Replacement value for IgnitionTime

See Also: ICWFGM_Ignition::SetIgnitionTime

Return values

S_OK	Successful
ERROR_SCENARIO_SIMULATION_RUNNING	If trying to set a new start time when the fire is attached to a running simulation

STDMETHODIMP CCWFGM_Ignition::SetIgnitionWKB	(	ULONG	index,
		SAFEARRAY *	wkb
	)

This method sets the ignition for this fire. This data cannot be modified when the fire object is attached to a running simulation. The arrray is in Well Known Binary. The units for x, y are in grid units, not in metres, etc.

Parameters

index	Where to insert this sub-ignition
wkb	An array of WKB bytes

See Also: CCWFGM_Ignition::SetIgnition

COM Programmer Documentation

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation