Platform SDK: Exchange 2000 Server

Advance Method

[This is preliminary documentation and subject to change.]

Evaluates the action table for this process instance and executes appropriate actions. This method is called internally by the CDO Workflow Event Sink, and does not need to be used by most applications.

Visual Basic]
Function Advance(eEventType As CdoWfEventType, _
                 varReceived, _
                 varUserID, 
                 [pConnection As Connection])
                 As Boolean
[C++]
HRESULT Advance(
                CdoWfEventType eEventType, 
                VARIANT varReceived, 
                VARIANT varUserID, 
                _Connection* pConnection, 
                VARIANT_BOOL* pbEnd);

[IDL]
HRESULT Advance(
                [in] CdoWfEventType eEventType, 
                [in] VARIANT varReceived, 
                [in] VARIANT varUserID, 
                [in, optional, defaultvalue(0)] _Connection* pConnection, 
                  [out, retval] VARIANT_BOOL* pbEnd);

Remarks

The event type can be one of the events in the CdoWfEventType enumeration. You only use this method if you are writing your own workflow event sink.

If the return value is true, it means the Process Instance entered a state marked as the end state.

This method and its supporting implementation is what we call the workflow engine. Normally you will not need to use this method, as the workflow event sink invokes it for you in response to an event in your folder. When the event sink calls, the engine looks for a row in your ActionTable that matches the CdoWfEventType passed to it and contains a condition field which evaluates to 'TRUE'. If it does not find a match with a 'TRUE' condition, it treats it as an error and returns the code CDOWF_NO_CONDS_MATCHED. If you want to allow editing of a workflow document without changing state, enter a transition in your ActionTable with a 'TRUE' condition and no action.

Advance includes an input parameter of type pointer to ActiveX Data Objects Connection. The workflow engine uses this parameter to supply the same session as the ProcessInstance to SendWorkflowMessage(). This ensures that email sent in conjunction with the ProcessInstance transaction is committed or aborted along with the ProcessInstance.

Example

[Visual Basic]
Dim eventType as CdoWfEventType
'check for what type of synchronous event to handle
'assume a delete event for this example
eventType = CdoWfOnDelete

Dim varReceived as Variant
'if this is a correlated email response
'get the item that initiated the event
'call it Row for this example
varReceived = Row

Dim varUserID as Variant
'get the security ID of the use that initiated the event
'call it Sid for this example
varUserID = Sid

Dim pConnection as Connection
'if this event involves an email response
'get event sink logon session for this transaction
'call it pConn
pConnection = pConn

Dim iPI as CDOWF.ProcessInstance
Dim bEnd as Boolean
bEnd = iPI.Advance(eventType, _
                   varReceived, _
                   varUserID, _
                   pConnection)