IPreflightProcess Class Reference

#include <IPreflightProcess.h>

Inheritance diagram for IPreflightProcess:

Public Types
enum	{ kDefaultIID = IID_IPREFLIGHTPROCESS }
enum	OperatingState {   kNothingToDo, kInitializing, kWaitingForComposition, kExpandingTree,   kVisitingTree, kResultsComplete }
enum	PauseState { kRunning = 0, kDocumentClosed, kUserPaused }
enum	PriorityType { kInactive, kLowPriority, kHighPriority }
enum	NodeType {   kInvalidNodeType, kRoot, kObject, kResult,   kDirectory }
enum	LinkType { kInvalidLinkType, kOwnership, kReference, kTemporary }
typedef uint32	NodeID
typedef K2Vector< NodeID >	NodeIDVector
typedef uint32	LinkID

Public Member Functions
virtual uint32	GetUniqueID () const =0
virtual void	SetUniqueID (uint32 id)=0
virtual uint32	GetTimeStamp () const =0
virtual ClassID	GetSelector () const =0
virtual void	SetSelector (ClassID selID)=0
virtual PreflightDocumentID	GetDocumentID () const =0
virtual void	SetDocumentID (const PreflightDocumentID &newDocID)=0
virtual void	SetIsBookProcess (bool newState)=0
virtual bool	IsBookProcess () const =0
virtual bool	GetAutoDelete () const =0
virtual void	SetAutoDelete (bool newState)=0
virtual void	Clear ()=0
virtual void	SetOptions (const IPreflightOptions *iOptions)=0
virtual const IPreflightOptions *	QueryOptions () const =0
virtual const IPreflightProfile *	QueryProfile () const =0
virtual void	SetProfile (IPreflightProfile *iProfile)=0
virtual OperatingState	GetState () const =0
virtual PauseState	GetPaused () const =0
virtual void	SetPaused (PauseState newState)=0
virtual bool	IsActive () const =0
virtual PriorityType	GetPriority () const =0
virtual void	AdvanceState (IdleTimer *timer, bool synchronous)=0
virtual IPreflightAggregatedResults *	CreateAggregatedResults () const =0
virtual NodeID	GetRootNode () const =0
virtual NodeID	GetRootObjectNode () const =0
virtual NodeType	GetNodeType (NodeID node) const =0
virtual LinkType	GetLinkType (LinkID link) const =0
virtual void	GetParentNodes (NodeID node, NodeIDVector &parents) const =0
virtual void	GetChildNodes (NodeID node, NodeIDVector &children) const =0
virtual LinkID	GetFirstParentLink (NodeID node) const =0
virtual LinkID	GetNextParentLink (LinkID link) const =0
virtual LinkID	GetFirstChildLink (NodeID node) const =0
virtual LinkID	GetNextChildLink (LinkID link) const =0
virtual NodeID	GetLinkParentNode (LinkID link) const =0
virtual NodeID	GetLinkChildNode (LinkID link) const =0
virtual void	GetObjectNodeObjectID (NodeID node, PreflightObjectID &objID) const =0
virtual void	GetResultNodes (NodeIDVector &results) const =0
virtual PreflightRuleID	GetResultNodeRuleID (NodeID resultNode) const =0
virtual IPreflightResultRecordTable *	QueryResultNodeTable (NodeID resultNode) const =0
virtual void	InvalidateObject (const PreflightObjectID &objID)=0
virtual void	InvalidateDocument ()=0
virtual void	OnSettingsChange (const IPreflightSettingsChangeInfo *iInfo)=0
virtual PMString	GetDescription () const =0
virtual PMString	GetResults () const =0
virtual PMString	GetInventory () const =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 interface sits on a preflight process boss and tracks the status of a particular preflight operation (either the background process we use in the UI or a synchronous one you create yourself via IPreflightProcessManager).

In addition to the state/status, it also maintains a database of raw results. This database tracks not only the results but the entire preflight DOM used for the process. Normally you don't inspect the raw results directly (though you can) but rather use the aggregated results, which are a prettified version with user-facing strings and organization.

You normally get this interface from IPreflightProcessManager. To find the processes for a given document, for example, use IPreflightProcessManager::GetProcessesForDocument or use IPreflightUtils::QueryProcessForDocument() if you want the process for the document that the preflight UI is using.

Member Typedef Documentation

typedef uint32 IPreflightProcess::LinkID

Links are a parent-child data structure that also maintain next- and prev- of same parent node, and next- and prev- of same child node. Ie an arbitrary graph of nodes. Each link also has a type (ownership vs reference).

typedef uint32 IPreflightProcess::NodeID

Nodes in the database. Zero means invalid.

typedef K2Vector<NodeID> IPreflightProcess::NodeIDVector

A vector of node IDs, used for various "get all of X" methods.

Member Enumeration Documentation

enum IPreflightProcess::LinkType

This enum identifies the link type.

Enumerator
kInvalidLinkType	General failure/invalid case.
kOwnership	The parent object owns the child. A node can actually have multiple owners. The idea is that if a node runs out of ownership parents, it is deleted.
kReference	The parent only references the child, so it won't protect it from deletion.
kTemporary	Temporary links are used for bookkeeping during the object discovery (expansion) phase.

enum IPreflightProcess::NodeType

This enum identifies the node category. Depending on the category you can ask different questions.

Enumerator
kInvalidNodeType	General failure/invalid case.
kRoot	The root of all nodes in the database.
kObject	A preflight object.
kResult	A result node.
kDirectory	A directory node, ie children are bird of some kind of feather.

enum IPreflightProcess::OperatingState

States a process can be in at any point in time (see GetState()).

Enumerator
kNothingToDo	The process isn't set up with any document, or the profile has no rules active.
kInitializing	Starting up (initially or after a clear-everything change).
kWaitingForComposition	To avoid thrashing, processes wait until composition is complete.
kExpandingTree	Walking DOM and building graph of object relationships.
kVisitingTree	Actually visiting DOM elements.
kResultsComplete	Results are up to date.

enum IPreflightProcess::PauseState

Processes can be paused; they still get invalidated but they won't get validation cycles until they're unpaused.

Enumerator
kRunning	Ie not paused.
kDocumentClosed	Document is no longer open. (This applies when book preflighting.)
kUserPaused	Preflighting is paused because the user paused it.

enum IPreflightProcess::PriorityType

Processes can have differing priorities depending on their state. See GetPriority().

Enumerator
kInactive	All results are current or there is nothing to do or the process is paused. No point in calling AdvanceState.
kLowPriority	In a holding pattern, waiting for text composition or delayed expansion. Should be called on a regular basis but not with high frequency because it'll simply return.
kHighPriority	There is work to be done. The higher the callback frequency, the more work will get done in the same amount of time.

Member Function Documentation

virtual void IPreflightProcess::AdvanceState ( IdleTimer *  timer, bool  synchronous  )

pure virtual

Give a time slice to do some work.

Parameters

timer

IN The timer which tells the process how much time it can use. Can be nil, indicating the process should work synchronously.

synchronous

IN Set this to true if you are calling this in a tight loop where (for example) the text composer will not be given any time to work; otherwise the process will never (or only extremely slowly) complete. When true, text composition will be forced synchronously prior to preflight expansion and visitation. Set this parameter to false if you're calling it from an idle loop where the text composer has a chance to operate efficiently.

virtual void IPreflightProcess::Clear ( )

pure virtual

Clear all tasks, the database, everything.

virtual IPreflightAggregatedResults* IPreflightProcess::CreateAggregatedResults ( ) const

pure virtual

Create an aggregated version of the results. This is the version that drives the UI, and rules are given the opportunity to condense all results into an "aggregated" form.

Returns

A refcounted aggregated results, or nil if some kind of error occurs.

virtual bool IPreflightProcess::GetAutoDelete ( ) const

pure virtual

Get the auto-delete property. If true the process will be deleted automatically if the document (or book, if the process is associated with a book) is closed. If false, the process is not automatically deleted.

Returns

The auto-delete state.

virtual void IPreflightProcess::GetChildNodes ( NodeID  node, NodeIDVector &  children  ) const

pure virtual

Get all the child nodes of a given node.

Parameters

node	IN The node for which you want the children.
parents	OUT Receives the list of child nodes.

virtual PMString IPreflightProcess::GetDescription ( ) const

pure virtual

This is for debugging purposes.

Returns

A string describing the state of the process. Not localized.

virtual PreflightDocumentID IPreflightProcess::GetDocumentID ( ) const

pure virtual

Returns

The document this preflight is associated with. Note that this does NOT use IDocument because the life cycle of the process may or may not correspond to the open document.

See Also

IPreflightManager for document ID mapping services.

Returns

The ID of the associated document. All preflight processes need a document.

virtual LinkID IPreflightProcess::GetFirstChildLink ( NodeID  node ) const

pure virtual

Get the first child link of a given node.

Parameters

node	IN The node you want the first child of.

Returns

The NodeID of the parent node, or 0 if the node has no children.

virtual LinkID IPreflightProcess::GetFirstParentLink ( NodeID  node ) const

pure virtual

Get the first parent link of a given node (note that nodes can have multiple parents). Once you have the link you can look "up" to the parent node, or "over" to the next parent.

Parameters

node	IN The child node whose first parent you want.

Returns

The NodeID of the parent node, or 0 if the child has no parent.

virtual PMString IPreflightProcess::GetInventory ( ) const

pure virtual

This is for debugging purposes.

Returns

A string containing a dump of the entire database. Not/partially localized.

virtual NodeID IPreflightProcess::GetLinkChildNode ( LinkID  link ) const

pure virtual

Given a parent-child link, get the child node.

Parameters

link	IN The link you want the child node for.

Returns

The NodeID of the child node. Will only be zero if the link is invalid (valid links always connect valid nodes).

virtual NodeID IPreflightProcess::GetLinkParentNode ( LinkID  link ) const

pure virtual

Given a parent-child link, get the parent node.

Parameters

link	IN The link you want the parent node for.

Returns

The NodeID of the parent node. Will only be zero if the link is invalid (valid links always connect valid nodes).

virtual LinkType IPreflightProcess::GetLinkType ( LinkID  link ) const

pure virtual

Given a link, get its type.

Parameters

link	IN THe link you're interested in.

Returns

The link type, or kInvalidLinkType if link ID is invalid or error occurs.

virtual LinkID IPreflightProcess::GetNextChildLink ( LinkID  link ) const

pure virtual

Get the next child link (ie same parent, a different child).

Parameters

link	IN The 'current' link, the one you want the next sibling of.

Returns

The LinkID of the next child link, or 0 if the link has no next sibling.

virtual LinkID IPreflightProcess::GetNextParentLink ( LinkID  link ) const

pure virtual

Get the next parent link of the same child node.

Parameters

node	IN The current parent link.

Returns

The LinkID of the next parent link, or 0 if the link has no next parent sibling.

virtual NodeType IPreflightProcess::GetNodeType ( NodeID  node ) const

pure virtual

Given a node, get its type.

Parameters

node	IN THe node you're interested in.

Returns

The node type, or kInvalidNodeType if node is invalid or error occurs.

virtual void IPreflightProcess::GetObjectNodeObjectID ( NodeID  node, PreflightObjectID &  objID  ) const

pure virtual

For object nodes, get the preflight object ID.

Parameters

node	IN The object node you're interested in.
objID	OUT Receives the object ID, or an invalid ID if the node isn't valid, or isn't an object node.

virtual void IPreflightProcess::GetParentNodes ( NodeID  node, NodeIDVector &  parents  ) const

pure virtual

Get all the parent nodes of a given node.

Parameters

node	IN The node for which you want the parents.
parents	OUT Receives the list of parent nodes.

virtual PauseState IPreflightProcess::GetPaused ( ) const

pure virtual

Gets whether the process is paused, and if so, why.

Returns

The pause state.

virtual PriorityType IPreflightProcess::GetPriority ( ) const

pure virtual

Checks the current state and returns a performance priority.

Returns

The priority code.

virtual PreflightRuleID IPreflightProcess::GetResultNodeRuleID ( NodeID  resultNode ) const

pure virtual

For a given result node ID, obtain the rule ID of that node.

virtual void IPreflightProcess::GetResultNodes ( NodeIDVector &  results ) const

pure virtual

Obtains a vector of all results nodes.

Parameters

results

OUT Receives the vector of result node IDs.

virtual PMString IPreflightProcess::GetResults ( ) const

pure virtual

This is for debugging purposes.

Returns

A string describing the errors found. Not (or only partially) localized.

virtual NodeID IPreflightProcess::GetRootNode ( ) const

pure virtual

Get the root node in the database – note that this is NOT the same as the root object node! The root node is a logical root, whereas the root object (ie, the document object) sits under the root. Remember, the database contains more than just object nodes.

Returns

The ID of the root node. This is a node of type kRoot.

virtual NodeID IPreflightProcess::GetRootObjectNode ( ) const

pure virtual

Get the root OBJECT node in the database – note that this is NOT the same as the root node! The root node is a logical root, whereas the root object (ie, the document object) sits under the root. Remember, the database contains more than just object nodes.

Returns

The ID of the root object node, ie the document object. This is a node of type kObject.

virtual ClassID IPreflightProcess::GetSelector ( ) const

pure virtual

Gets the selector ID for the process. This is simply a way of tagging the owner of the process so the owner can find it later. For example preflight uses the kPreflightContinuousProcessSelectorID selector to indicate the current continous (background) preflighting process, as opposed to some ad-hoc process it might create for other reasons.

Note that this is purely a tagging mechanism. The process doesn't do anything with the selector ID except store it.

Returns

The selector.

virtual OperatingState IPreflightProcess::GetState ( ) const

pure virtual

Get the current state of the process.

Returns

The state.

virtual uint32 IPreflightProcess::GetTimeStamp ( ) const

pure virtual

Returns the modification 'time stamp' – not really a time at all, but a change number that indicates whether the state of the database is the same as the last time you checked. Every time there's a change this number is bumped by one.

Returns

The current "time stamp" identifier.

virtual uint32 IPreflightProcess::GetUniqueID ( ) const

pure virtual

Get the unique ID of this process. This number is generated automatically by the process manager in all cases where the process is created via the manager.

Returns

The process's unique ID. This is unique within a given ID session.

virtual void IPreflightProcess::InvalidateDocument ( )

pure virtual

Invalidate the root document object. This clears out the document tree and forces a complete rebuild of all results. Same result as if you got the document object ID and called InvalidateObject.

virtual void IPreflightProcess::InvalidateObject ( const PreflightObjectID &  objID )

pure virtual

Invalidate the specified object in the process (if that object exists). This clips the subtree below the node and adds the node to the expansion and visitation list.

Parameters

objID

IN The object to invalidate.

virtual bool IPreflightProcess::IsActive ( ) const

pure virtual

Same as checking for state != kResultsComplete && state != kNothingToDo && paused == kRunning.

Returns

True if the process has something to do; False if complete or nothing to do.

virtual bool IPreflightProcess::IsBookProcess ( ) const

pure virtual

Get whether there are books associated with this process.

See Also

SetIsBookProcess.

Returns

kTrue if the process is book-affiliated; kFalse otherwise.

virtual void IPreflightProcess::OnSettingsChange ( const IPreflightSettingsChangeInfo *  iInfo )

pure virtual

Called on a process via the process manager (usually) to indicate that settings may have changed for the given database. (Profile change, deleted profile, options, etc.) Process needs to double-check settings and/or invalidate as appropriate.

Parameters

iInfo

IN The event information to respond to.

virtual const IPreflightOptions* IPreflightProcess::QueryOptions ( ) const

pure virtual

Query the current options. Note that you can't modify these options, just look at them.

Returns

The current options, refcounted.

virtual const IPreflightProfile* IPreflightProcess::QueryProfile ( ) const

pure virtual

Get the profile used for this preflight process. Const because it may come from someplace that wouldn't want it to be modified.

Returns

A refcounted profile interface.

virtual IPreflightResultRecordTable* IPreflightProcess::QueryResultNodeTable ( NodeID  resultNode ) const

pure virtual

For a given result node ID, obtain the table of recorded results.

virtual void IPreflightProcess::SetAutoDelete ( bool  newState )

pure virtual

Set the auto-delete property. If true the process will be deleted automatically if the document (or book, if the process is associated with a book) is closed. If false, the process is not automatically deleted.

Parameters

newState

IN The new auto-delete state.

virtual void IPreflightProcess::SetDocumentID ( const PreflightDocumentID &  newDocID )

pure virtual

Set the document this preflight is associated with. This is typically done only when the process is first created. Note that this does NOT use IDocument because the life cycle of the process may or may not correspond to the open document.

See Also

IPreflightManager for document ID mapping services.

Parameters

newDocID

IN The new document ID.

virtual void IPreflightProcess::SetIsBookProcess ( bool  newState )

pure virtual

Set whether there are books associated with this process. That is, this process's results are used (either actively or not, in the case of a closed document) to provide the current preflight errors for a document associated with a book. Note that a process can in theory be associated with more than one book (if it happens to match multiple books' settings). Also, note that this boolean doesn't mean that it isn't the active preflight for a document as well. The impetus for this flag is that when a process is associated with a book and the document is closed, the process is not automatically destroyed.

Parameters

newState

IN kTrue if the process is book-affiliated; kFalse otherwise.

virtual void IPreflightProcess::SetOptions ( const IPreflightOptions *  iOptions )

pure virtual

Set the options to use for this process. This method makes a COPY of the options.

Parameters

iOptions

IN The options. Can't be nil. A copy is made so refcount is unchanged.

virtual void IPreflightProcess::SetPaused ( PauseState  newState )

pure virtual

Sets whether the process is paused, and if so, why.

Parameters

newState

The new paused state.

virtual void IPreflightProcess::SetProfile ( IPreflightProfile *  iProfile )

pure virtual

Set the profile used for this preflight process. This references the profile, unless the profile is one associated with a document (as opposed to the application), in which case a copy of the profile is made so that the process (and all its associated data) can still live with the document closed. (This is needed for book preflight, for example.)

Parameters

iProfile

IN The profile to use.

virtual void IPreflightProcess::SetSelector ( ClassID  selID )

pure virtual

Sets the selector ID for the process.

See Also

GetSelector for what this is.

Parameters

selID

IN The new selector ID.

virtual void IPreflightProcess::SetUniqueID ( uint32  id )

pure virtual

Set the unique ID of the process. This should not be called for any process that is created by the process manager, as changing it will affect all kinds of caches.

Parameters

id	IN The new unique ID.