ITransactionPhase0Factory::Create

 

Applies To: Windows 10, Windows 7, Windows 8, Windows 8.1, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2, Windows Server Technical Preview, Windows Vista

This method creates the Phase0 Enlistment object and exchanges the ITransactionPhase0NotifyAsync and ITransactionPhase0EnlistmentAsync sinks between the Phase0 participant and the DTC proxy. A Phase0 participant invokes this method on the transaction object for any transaction on which it needs notification of phase0 events. The lifetime of a Phase0 Enlistment object matches that of the transaction with which it is associated, unless it is released sooner.

A Phase0 Enlistment object is considered a "single-shot" enlistment That is, a Phase0 enlistment object will produce one and only one Phase0 notification. If a Phase0 participant wishes to receive additional phase0 notifications (for example, if additional work were received after having completed one bout of Phase0 processing), additional Phase0 Enlistment objects should be created.

The enlistment object is created in the "disabled" state; no callbacks (either Phase0Request or EnlistCompleted) will be received on the Notify interface until the enlistment has been "enabled" via the Enable method. This avoids the race condition that otherwise results, wherein a callback arrives before the [out] parameter has been set on return from the Create method (so the participant has not received the Phase0 enlistment object pointer on which to respond).

The enlistment with the transaction manager occurs asynchronously; a client application that prefers to use a synchronous-style interface (for example, block until the enlistment has completed) should call WaitForEnlistment after Create. Note that the successful return of the Create method does not necessarily indicate that the enlistment will succeed. Successful enlistment can be determined only by checking the status parameter returned to WaitForEnlistment or passed to the ITransactionPhase0NotifyAsync::EnlistCompleted callback.

The last Release of the ITransactionPhase0Enlistment interface pointer returned via Create causes the Phase0 enlistment object to be destructed. This may or may not cause the associated transaction to abort, depending on the state of the enlistment object. If the phase0 enlistment object is in a "done" state (for example, the participant has already called Phase0Done, or Unenlist), an abort is not implied. If the phase0 enlistment object is in a state that implies a phase0 notification is still pending (for example, the "disabled" state, the "active" state, or the "phase0" state), then releasing the object would imply an abort.

Syntax

  
      HRESULT Create( ITransactionPhase0NotifyAsync * pITransactionPhase0Notify,   
  ITransactionPhase0EnlistmentAsync ** ppITransactionPhase0Enlistment  
);  

Parameters

pITransactionPhase0Notify
[in] Pointer to the ITransactionPhase0NotifyAsync sink exported by the participant.

ppITransactionPhase0Enlistment
[out] Pointer to a pointer of an ITransactionPhase0EnlistmentAsync interface via which the participant can indicate the completion of phase0 processing.

Return Values

S_OK
Success—the transaction completed.

E_INVALIDARG
Failure—one or more of the parameters are not valid.

E_OUTOFMEMORY
Failure—unable to allocate memory.

E_UNEXPECTED
Failure—an unexpected error occurred.

Requirements

For an explanation of the requirement values, see Requirements (Component Services).

Platforms: Windows Server 2016, Windows 10, Windows Server 2012 R2, Windows 8.1, Windows Server 2012, Windows 8, Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista

Header: Declared in txdtc.h

See Also

ITransactionPhase0EnlistmentAsync
ITransactionPhase0NotifyAsync