IPreflightAggregatedResults Class Reference

#include <IPreflightAggregatedResults.h>

Inheritance diagram for IPreflightAggregatedResults:

Public Types
enum	{ kDefaultIID = IID_IPREFLIGHTAGGREGATEDRESULTS }
typedef uint32	NodeID
typedef K2Vector< NodeID >	NodeIDVector

Public Member Functions
virtual bool	IsValidID (NodeID node) const =0
virtual NodeID	GetRoot () const =0
virtual void	Clear ()=0
virtual NodeID	AddNode (NodeID parentNode, IPreflightResultNodeInfo *iInfo)=0
virtual void	DeleteNode (NodeID node)=0
virtual NodeID	GetParent (NodeID child) const =0
virtual int32	GetNumChildren (NodeID parent) const =0
virtual NodeID	GetFirstChild (NodeID node) const =0
virtual NodeID	GetNextSibling (NodeID node) const =0
virtual int32	GetChildIndex (NodeID parent, NodeID child) const =0
virtual int32	GetHierarchyDepth (NodeID node) const =0
virtual IPreflightResultNodeInfo *	QueryNodeInfo (NodeID node) const =0
virtual uint32	GetChildren (IPreflightAggregatedResults::NodeID parentNode, IPreflightResultNodeInfo::NodeType nodeType=IPreflightResultNodeInfo::kInvalid, bool recursive=kFalse, NodeIDVector *pNodes=nil) const =0
virtual int32	CopyNodesFrom (IPreflightAggregatedResults::NodeID dstParentNode, const IPreflightAggregatedResults *iSrcResults, IPreflightAggregatedResults::NodeID srcRootNode, bool copyRootNode)=0
Public Member Functions inherited from IPMUnknown
virtual IPMUnknown *	QueryInterface (PMIID interfaceID) const =0
virtual void	AddRef () const =0
virtual void	Release () const =0

Detailed Description

This is an in-memory database of preflight results AFTER the rules and the engine have finished finding any/all problems. Generally speaking the results found in the expansion/visitation phase are "raw" and need to be consolidated in different ways depending on the rule and where the violations occur. That's the purpose of this secondary structure.

This interface sits on a boss in memory; it's not persistent. Normally this boss is created by the preflight process via IPreflightProcess::CreateAggregatedResults(). However, once built the interface is no longer dependent on that process. This is to support user interface, which is where this interface usually matters: presenting the results or dumping them to a file somewhere, and you need something that's stable even if the document changes and the process dumps its internal database and starts over. Having said that you must be careful when asking about nodes whose references may be stable (

See Also

IPreflightResultNodeInfo).

This interface simply provides the structure of the database. More detailed information about each node is obtained via QueryNodeInfo().

Member Function Documentation

virtual NodeID IPreflightAggregatedResults::AddNode ( NodeID  parentNode, IPreflightResultNodeInfo *  iInfo  )

pure virtual

Add a node to the database as a child of an existing node. Note that the child is not (generally) appended to the child list; it's added according to IPreflightResultNodeInfo::GetSortValue ordering.

Parameters

parentNode	IN The parent node.
iInfo	IN The information to associate with the node (will be refcounted).

Returns

The node ID of the newly added node.

virtual void IPreflightAggregatedResults::Clear ( )

pure virtual

Clear the database back to it default state, a single root node with no children.

virtual int32 IPreflightAggregatedResults::CopyNodesFrom ( IPreflightAggregatedResults::NodeID  dstParentNode, const IPreflightAggregatedResults *  iSrcResults, IPreflightAggregatedResults::NodeID  srcRootNode, bool  copyRootNode  )

pure virtual

Copy nodes from another results tree into this one. Note that this does only reference counting on the child nodes, not a true data copy.

Parameters

dstParentNode	IN The parent node in THIS tree under which the nodes from the source tree should be copied.
iSrcResults	IN The tree from which nodes should be copied.
srcRootNode	IN The root node at which to start copying.
copyRootNode	IN True to copy the root node; false to copy only its children.

Returns

The number of nodes actually copied.

virtual void IPreflightAggregatedResults::DeleteNode ( NodeID  node )

pure virtual

Delete the specified node. Also deletes all children. The refcount is released on the related IPreflightResultNodeInfo.

CAUTION: This is a limited-use function as the aggregated results are designed primarily for additions, not modifications. In particular the node ID and memory used by the node are not recovered, just marked as no longer used. This may be improved in future versions.

Parameters

node	IN The ID of the node to delete.

virtual int32 IPreflightAggregatedResults::GetChildIndex ( NodeID  parent, NodeID  child  ) const

pure virtual

Given a node ID, return the index of that node in the parent's child list. This is simply a convenience method based on GetParent, GetFirstChild, etc.

Parameters

parent	IN The parent node.
child	IN The child node.

Returns

The index of the child in the parent, or -1 if the child is not a child of the parent.

virtual uint32 IPreflightAggregatedResults::GetChildren ( IPreflightAggregatedResults::NodeID  parentNode, IPreflightResultNodeInfo::NodeType  nodeType = IPreflightResultNodeInfo::kInvalid, bool  recursive = kFalse, NodeIDVector *  pNodes = nil  ) const

pure virtual

General-case method for obtain child/descendent information that saves you the trouble of looping over the enumerators above.

Parameters

parentNode	IN The node whose children/descendents you're interested in.
nodeType	IN The node type to filter by, or kInvalid to not filter by node type.
recursive	IN True to recurse (ie, all descendents) or false to only consider immediate children.
pNodes	OUT If not nil, receives the list of matching child nodes.

Returns

The number of matching nodes.

virtual NodeID IPreflightAggregatedResults::GetFirstChild ( NodeID  node ) const

pure virtual

Get the first child of a node.

Parameters

node	IN The node you want the child of.

Returns

The ID of the first child node, or 0 if unsuccessful.

virtual int32 IPreflightAggregatedResults::GetHierarchyDepth ( NodeID  node ) const

pure virtual

Get the depth of the hierarchy. The depth of the root is zero; all others are indexed from there. This is simply a convenience method based on GetParent().

Returns

The depth of the node in the hierarchy.

virtual NodeID IPreflightAggregatedResults::GetNextSibling ( NodeID  node ) const

pure virtual

Get the next sibling of a node.

Parameters

node	IN The node you want the next sibling of.

Returns

The ID of the next sibling node, or 0 if unsuccessful.

virtual int32 IPreflightAggregatedResults::GetNumChildren ( NodeID  parent ) const

pure virtual

Get the number of child nodes.

Parameters

child

IN The node you're interested in.

Returns

The number of children of the node; 0 if none or error.

virtual NodeID IPreflightAggregatedResults::GetParent ( NodeID  child ) const

pure virtual

Get the parent of a node, if any.

Parameters

child

IN The node you want the parent of.

Returns

The parent node ID, or 0 if there is no parent (ie child is invalid or the root).

virtual NodeID IPreflightAggregatedResults::GetRoot ( ) const

pure virtual

Return the root node of the results tree.

Returns

The ID of the root or 0 if there is no root.

virtual bool IPreflightAggregatedResults::IsValidID ( NodeID  node ) const

pure virtual

Returns whether a node ID is valid.

Parameters

node	IN The node in which you're interested.

Returns

kTrue if valid, kFalse if not.

virtual IPreflightResultNodeInfo* IPreflightAggregatedResults::QueryNodeInfo ( NodeID  node ) const

pure virtual

Given a node, get the preflight result interface for more information about that node.

Parameters

node	IN The ID of the node in which you're interested.

Returns

A refcounted information node, or nil if unsuccessful. Not all nodes will have information, but in practice the only node that shouldn't is the root node. Note that the returned interface won't usually be boss-based but rather a simple structure. Nevertheless it still follows IPMUnknown rules for lifecycle management – that is, you MUST dereference it when you're done!