MsiJoinTransaction function (msi.h)

The MsiJoinTransaction function requests that the Windows Installer make the current process the owner of the transaction installing the multiple-package installation.

Windows Installer 4.0 and earlier:  Not supported. This function is available beginning with Windows Installer 4.5.

Syntax

UINT MsiJoinTransaction(
  [in]  MSIHANDLE hTransactionHandle,
  [in]  DWORD     dwTransactionAttributes,
  [out] HANDLE    *phChangeOfOwnerEvent
);

Parameters

[in] hTransactionHandle

The transaction ID, which identifies the transaction and is the identifier returned by the MsiBeginTransaction function.

[in] dwTransactionAttributes

Attributes of the multiple-package installation.

Value Meaning
0
When 0 or no value is set, Windows Installer closes the UI from the previous installation.
MSITRANSACTION_CHAIN_EMBEDDEDUI
Set this attribute to request that the Windows Installer not shutdown the embedded UI until the transaction is complete.
MSITRANSACTION_JOIN_EXISTING_EMBEDDEDUI
Set this attribute to request that the Windows Installer transfer the embedded UI from the original installation. If the original installation has no embedded UI, setting this attribute does nothing.

[out] phChangeOfOwnerEvent

This parameter returns a handle to an event that is set when the MsiJoinTransaction function changes the owner of the transaction to a new owner. The current owner can use this to determine when ownership of the transaction has changed. Leaving a transaction without an owner will roll back the transaction.

Return value

The MsiJoinTransaction function can return the following values.

Value Meaning
ERROR_ACCESS_DENIED
The user that owns the transaction and the user that joins the transaction are not the same.
ERROR_INVALID_PARAMETER
A parameter that is not valid is passed to the function.
ERROR_INSTALL_ALREADY_RUNNING
The owner cannot be changed while an active installation is in progress.
ERROR_INVALID_HANDLE_STATE
The transaction ID provided is not valid.

Remarks

Because a transaction can be owned by no more than one process at a time, the functions authored into the MsiEmbeddedChainer table can use MsiJoinTransaction to request ownership of the transaction before using the Windows Installer API to configure or install an application. The installer verifies that there is no installation in progress. The installer verifies that the process requesting ownership and the process that currently owns the transaction share a parent process in the same process tree. If the function succeeds, the process that calls MsiJoinTransaction becomes the current owner of the transaction.

MsiJoinTransaction sets the internal UI of the new installation to the UI level of the original installation. After the new installation owns the transaction, it can call MsiSetInternalUI to change the UI level. This enables the new installation to run at a higher UI level than the original installation.

Requirements

Requirement Value
Minimum supported client Windows Installer 5.0 on Windows Server 2012, Windows 8, Windows Server 2008 R2 or Windows 7. Windows Installer 4.5 on Windows Vista, Windows XP, Windows Server 2003, and Windows Server 2008. See the Windows Installer Run-Time Requirements for information about the minimum Windows service pack that is required by a Windows Installer version.
Target Platform Windows
Header msi.h
Library Msi.lib
DLL Msi.dll

See also

Multiple Package Installations