Edit

Share via

MsiBeginTransactionA function (msi.h)

  • Article

The MsiBeginTransaction function starts transaction processing of a multiple-package installation and returns an identifier for the transaction. The MsiEndTransaction function ends the transaction.

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

Syntax

UINT MsiBeginTransactionA(
  [in]  LPCSTR    szName,
  [in]  DWORD     dwTransactionAttributes,
  [out] MSIHANDLE *phTransactionHandle,
  [out] HANDLE    *phChangeOfOwnerEvent
);

Parameters

[in] szName

Name of the multiple-package installation.

[in] dwTransactionAttributes

Attributes of the multiple-package installation.

Value Meaning
0
 When 0 or no value is set it 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.

[out] phTransactionHandle

Transaction ID is a MSIHANDLE value that identifies the transaction. Only one process can own a transaction at a time.

[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 MsiBeginTransaction function returns the following values.

Value Meaning
ERROR_INSTALL_SERVICE_FAILURE
 The installation service could not be accessed. This function requires the Windows Installer service.
ERROR_INSTALL_ALREADY_RUNNING
 Only one transaction can be open on a system at a time. The function returns this error if called while another transaction is running.
ERROR_INVALID_PARAMETER
 An invalid parameter is passed to the function.
ERROR_ROLLBACK_DISABLED

Rollback Installations have been disabled by the DISABLEROLLBACK property or DisableRollback policy.

Remarks

Note

The msi.h header defines MsiBeginTransaction as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

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