Replace OnResolveSource with OnCacheAcquireResolving.

Update balretry to have a separate type for container vs payload.

#3640

4 files changed, 168 insertions, 118 deletions

diff --git a/src/WixToolset.Mba.Core/BootstrapperApplication.cs b/src/WixToolset.Mba.Core/BootstrapperApplication.cs
index b6c0dd0d..79cbfa86 100644
--- a/src/WixToolset.Mba.Core/BootstrapperApplication.cs
+++ b/src/WixToolset.Mba.Core/BootstrapperApplication.cs
@@ -146,7 +146,7 @@ namespace WixToolset.Mba.Core
         public event EventHandler<CacheAcquireProgressEventArgs> CacheAcquireProgress;
 
         /// <inheritdoc/>
-        public event EventHandler<ResolveSourceEventArgs> ResolveSource;
+        public event EventHandler<CacheAcquireResolvingEventArgs> CacheAcquireResolving;
 
         /// <inheritdoc/>
         public event EventHandler<CacheAcquireCompleteEventArgs> CacheAcquireComplete;
@@ -736,12 +736,12 @@ namespace WixToolset.Mba.Core
         }
 
         /// <summary>
-        /// Called by the engine, raises the <see cref="ResolveSource"/> event.
+        /// Called by the engine, raises the <see cref="CacheAcquireResolving"/> event.
         /// </summary>
         /// <param name="args">Additional arguments for this event.</param>
-        protected virtual void OnResolveSource(ResolveSourceEventArgs args)
+        protected virtual void OnCacheAcquireResolving(CacheAcquireResolvingEventArgs args)
         {
-            EventHandler<ResolveSourceEventArgs> handler = this.ResolveSource;
+            EventHandler<CacheAcquireResolvingEventArgs> handler = this.CacheAcquireResolving;
             if (null != handler)
             {
                 handler(this, args);
@@ -1126,9 +1126,9 @@ namespace WixToolset.Mba.Core
             return args.HResult;
         }
 
-        int IBootstrapperApplication.OnDetectBegin(bool fInstalled, int cPackages, ref bool fCancel)
+        int IBootstrapperApplication.OnDetectBegin(bool fCached, bool fInstalled, int cPackages, ref bool fCancel)
         {
-            DetectBeginEventArgs args = new DetectBeginEventArgs(fInstalled, cPackages, fCancel);
+            DetectBeginEventArgs args = new DetectBeginEventArgs(fCached, fInstalled, cPackages, fCancel);
             this.OnDetectBegin(args);
 
             fCancel = args.Cancel;
@@ -1400,11 +1400,12 @@ namespace WixToolset.Mba.Core
             return args.HResult;
         }
 
-        int IBootstrapperApplication.OnCacheAcquireBegin(string wzPackageOrContainerId, string wzPayloadId, CacheOperation operation, string wzSource, ref bool fCancel)
+        int IBootstrapperApplication.OnCacheAcquireBegin(string wzPackageOrContainerId, string wzPayloadId, string wzSource, string wzDownloadUrl, string wzPayloadContainerId, CacheOperation recommendation, ref CacheOperation action, ref bool fCancel)
         {
-            CacheAcquireBeginEventArgs args = new CacheAcquireBeginEventArgs(wzPackageOrContainerId, wzPayloadId, operation, wzSource, fCancel);
+            CacheAcquireBeginEventArgs args = new CacheAcquireBeginEventArgs(wzPackageOrContainerId, wzPayloadId, wzSource, wzDownloadUrl, wzPayloadContainerId, recommendation, action, fCancel);
             this.OnCacheAcquireBegin(args);
 
+            action = args.Action;
             fCancel = args.Cancel;
             return args.HResult;
         }
@@ -1418,11 +1419,12 @@ namespace WixToolset.Mba.Core
             return args.HResult;
         }
 
-        int IBootstrapperApplication.OnResolveSource(string wzPackageOrContainerId, string wzPayloadId, string wzLocalSource, string wzDownloadSource, BOOTSTRAPPER_RESOLVESOURCE_ACTION recommendation, ref BOOTSTRAPPER_RESOLVESOURCE_ACTION action, ref bool fCancel)
+        int IBootstrapperApplication.OnCacheAcquireResolving(string wzPackageOrContainerId, string wzPayloadId, string[] searchPaths, int cSearchPaths, bool fFoundLocal, int dwRecommendedSearchPath, string wzDownloadUrl, string wzPayloadContainerId, CacheResolveOperation recommendation, ref int dwChosenSearchPath, ref CacheResolveOperation action, ref bool fCancel)
         {
-            ResolveSourceEventArgs args = new ResolveSourceEventArgs(wzPackageOrContainerId, wzPayloadId, wzLocalSource, wzDownloadSource, action, recommendation, fCancel);
-            this.OnResolveSource(args);
+            CacheAcquireResolvingEventArgs args = new CacheAcquireResolvingEventArgs(wzPackageOrContainerId, wzPayloadId, searchPaths, fFoundLocal, dwRecommendedSearchPath, wzDownloadUrl, wzPayloadContainerId, recommendation, dwChosenSearchPath, action, fCancel);
+            this.OnCacheAcquireResolving(args);
 
+            dwChosenSearchPath = args.ChosenSearchPath;
             action = args.Action;
             fCancel = args.Cancel;
             return args.HResult;
diff --git a/src/WixToolset.Mba.Core/EventArgs.cs b/src/WixToolset.Mba.Core/EventArgs.cs
index 7e7cbd11..ee89b583 100644
--- a/src/WixToolset.Mba.Core/EventArgs.cs
+++ b/src/WixToolset.Mba.Core/EventArgs.cs
@@ -123,6 +123,31 @@ namespace WixToolset.Mba.Core
     }
 
     /// <summary>
+    /// Base class for cancellable action BA <see cref="EventArgs"/> classes.
+    /// </summary>
+    [Serializable]
+    public abstract class CancellableActionEventArgs<T> : CancellableHResultEventArgs
+    {
+        /// <summary />
+        public CancellableActionEventArgs(bool cancelRecommendation, T recommendation, T action)
+            : base(cancelRecommendation)
+        {
+            this.Recommendation = recommendation;
+            this.Action = action;
+        }
+
+        /// <summary>
+        /// Gets the recommended action from the engine.
+        /// </summary>
+        public T Recommendation { get; private set; }
+
+        /// <summary>
+        /// Gets or sets the action to be performed. This is passed back to the engine.
+        /// </summary>
+        public T Action { get; set; }
+    }
+
+    /// <summary>
     /// Additional arguments used when startup has begun.
     /// </summary>
     [Serializable]
@@ -196,25 +221,26 @@ namespace WixToolset.Mba.Core
     }
 
     /// <summary>
-    /// Additional arguments used when the overall detection phase has begun.
+    /// Event arguments for <see cref="IDefaultBootstrapperApplication.DetectBegin"/>
     /// </summary>
     [Serializable]
     public class DetectBeginEventArgs : CancellableHResultEventArgs
     {
-        /// <summary>
-        /// Creates a new instance of the <see cref="DetectBeginEventArgs"/> class.
-        /// </summary>
-        /// <param name="installed">Specifies whether the bundle is installed.</param>
-        /// <param name="packageCount">The number of packages to detect.</param>
-        /// <param name="cancelRecommendation">The recommendation from the engine.</param>
-        public DetectBeginEventArgs(bool installed, int packageCount, bool cancelRecommendation)
+        /// <summary />
+        public DetectBeginEventArgs(bool cached, bool installed, int packageCount, bool cancelRecommendation)
             : base(cancelRecommendation)
         {
+            this.Cached = cached;
             this.Installed = installed;
             this.PackageCount = packageCount;
         }
 
         /// <summary>
+        /// Gets whether the bundle is cached.
+        /// </summary>
+        public bool Cached { get; private set; }
+
+        /// <summary>
         /// Gets whether the bundle is installed.
         /// </summary>
         public bool Installed { get; private set; }
@@ -290,6 +316,7 @@ namespace WixToolset.Mba.Core
             : base(cancelRecommendation)
         {
             this.UpdateLocation = updateLocation;
+            this.Skip = skipRecommendation;
         }
 
         /// <summary>
@@ -1242,6 +1269,8 @@ namespace WixToolset.Mba.Core
         /// <param name="forceKeepRegistration"></param>
         public UnregisterBeginEventArgs(bool keepRegistration, bool forceKeepRegistration)
         {
+            this.KeepRegistration = keepRegistration;
+            this.ForceKeepRegistration = forceKeepRegistration;
         }
 
         /// <summary>
@@ -1288,21 +1317,20 @@ namespace WixToolset.Mba.Core
     }
 
     /// <summary>
-    /// Additional arguments used when the engine begins to acquire containers or payloads.
+    /// EventArgs for <see cref="IDefaultBootstrapperApplication.CacheAcquireBegin"/>.
     /// </summary>
     [Serializable]
-    public class CacheAcquireBeginEventArgs : CancellableHResultEventArgs
+    public class CacheAcquireBeginEventArgs : CancellableActionEventArgs<CacheOperation>
     {
-        /// <summary>
-        /// Creates a new instance of the <see cref="CacheAcquireBeginEventArgs"/> class.
-        /// </summary>
-        public CacheAcquireBeginEventArgs(string packageOrContainerId, string payloadId, CacheOperation operation, string source, bool cancelRecommendation)
-            : base(cancelRecommendation)
+        /// <summary />
+        public CacheAcquireBeginEventArgs(string packageOrContainerId, string payloadId, string source, string downloadUrl, string payloadContainerId, CacheOperation recommendation, CacheOperation action, bool cancelRecommendation)
+            : base(cancelRecommendation, recommendation, action)
         {
             this.PackageOrContainerId = packageOrContainerId;
             this.PayloadId = payloadId;
-            this.Operation = operation;
             this.Source = source;
+            this.DownloadUrl = downloadUrl;
+            this.PayloadContainerId = payloadContainerId;
         }
 
         /// <summary>
@@ -1316,25 +1344,28 @@ namespace WixToolset.Mba.Core
         public string PayloadId { get; private set; }
 
         /// <summary>
-        /// Gets the cache acquire operation.
+        /// Gets the source of the container or payload.
         /// </summary>
-        public CacheOperation Operation { get; private set; }
+        public string Source { get; private set; }
 
         /// <summary>
-        /// Gets the source of the container or payload.
+        /// Gets the optional URL to download container or payload.
         /// </summary>
-        public string Source { get; private set; }
+        public string DownloadUrl { get; private set; }
+
+        /// <summary>
+        /// Gets the optional identity of the container that contains the payload being acquired.
+        /// </summary>
+        public string PayloadContainerId { get; private set; }
     }
 
     /// <summary>
-    /// Additional arguments used when the engine acquires some part of a container or payload.
+    /// EventArgs for <see cref="IDefaultBootstrapperApplication.CacheAcquireProgress"/>.
     /// </summary>
     [Serializable]
     public class CacheAcquireProgressEventArgs : CancellableHResultEventArgs
     {
-        /// <summary>
-        /// Creates a new instance of the <see cref="CacheAcquireBeginEventArgs"/> class.
-        /// </summary>
+        /// <summary />
         public CacheAcquireProgressEventArgs(string packageOrContainerId, string payloadId, long progress, long total, int overallPercentage, bool cancelRecommendation)
             : base(cancelRecommendation)
         {
@@ -1372,14 +1403,12 @@ namespace WixToolset.Mba.Core
     }
 
     /// <summary>
-    /// Additional arguments used when the engine completes the acquisition of a container or payload.
+    /// EventArgs for <see cref="IDefaultBootstrapperApplication.CacheAcquireComplete"/>.
     /// </summary>
     [Serializable]
     public class CacheAcquireCompleteEventArgs : ActionEventArgs<BOOTSTRAPPER_CACHEACQUIRECOMPLETE_ACTION>
     {
-        /// <summary>
-        /// Creates a new instance of the <see cref="CacheAcquireCompleteEventArgs"/> class.
-        /// </summary>
+        /// <summary />
         public CacheAcquireCompleteEventArgs(string packageOrContainerId, string payloadId, int hrStatus, BOOTSTRAPPER_CACHEACQUIRECOMPLETE_ACTION recommendation, BOOTSTRAPPER_CACHEACQUIRECOMPLETE_ACTION action)
             : base(hrStatus, recommendation, action)
         {
@@ -1729,62 +1758,64 @@ namespace WixToolset.Mba.Core
     }
 
     /// <summary>
-    /// Additional arguments used by the engine to allow the BA to change the source
-    /// using <see cref="Engine.SetLocalSource"/> or <see cref="Engine.SetDownloadSource"/>.
+    /// EventArgs for <see cref="IDefaultBootstrapperApplication.CacheAcquireResolving"/>.
     /// </summary>
     [Serializable]
-    public class ResolveSourceEventArgs : CancellableHResultEventArgs
+    public class CacheAcquireResolvingEventArgs : CancellableActionEventArgs<CacheResolveOperation>
     {
-        /// <summary>
-        /// Creates a new instance of the <see cref="ResolveSourceEventArgs"/> class.
-        /// </summary>
-        /// <param name="packageOrContainerId">The identity of the package or container that requires source.</param>
-        /// <param name="payloadId">The identity of the payload that requires source.</param>
-        /// <param name="localSource">The current path used for source resolution.</param>
-        /// <param name="downloadSource">Optional URL to download container or payload.</param>
-        /// <param name="recommendation">The recommended action from the engine.</param>
-        /// <param name="action">The action to perform.</param>
-        /// <param name="cancelRecommendation">The recommendation from the engine.</param>
-        public ResolveSourceEventArgs(string packageOrContainerId, string payloadId, string localSource, string downloadSource, BOOTSTRAPPER_RESOLVESOURCE_ACTION recommendation, BOOTSTRAPPER_RESOLVESOURCE_ACTION action, bool cancelRecommendation)
-            : base(cancelRecommendation)
+        /// <summary />
+        public CacheAcquireResolvingEventArgs(string packageOrContainerId, string payloadId, string[] searchPaths, bool foundLocal, int recommendedSearchPath, string downloadUrl, string payloadContainerId, CacheResolveOperation recommendation, int chosenSearchPath, CacheResolveOperation action, bool cancel)
+            : base(cancel, recommendation, action)
         {
             this.PackageOrContainerId = packageOrContainerId;
             this.PayloadId = payloadId;
-            this.LocalSource = localSource;
-            this.DownloadSource = downloadSource;
-            this.Recommendation = recommendation;
-            this.Action = action;
+            this.SearchPaths = searchPaths;
+            this.FoundLocal = foundLocal;
+            this.RecommendedSearchPath = recommendedSearchPath;
+            this.DownloadUrl = downloadUrl;
+            this.PayloadContainerId = payloadContainerId;
+            this.ChosenSearchPath = chosenSearchPath;
         }
 
         /// <summary>
-        /// Gets the identity of the package or container that requires source.
+        /// Gets the identity of the package or container that is being acquired.
         /// </summary>
         public string PackageOrContainerId { get; private set; }
 
         /// <summary>
-        /// Gets the identity of the payload that requires source.
+        /// Gets the identity of the payload that is being acquired.
         /// </summary>
         public string PayloadId { get; private set; }
 
         /// <summary>
-        /// Gets the current path used for source resolution.
+        /// Gets the search paths used for source resolution.
         /// </summary>
-        public string LocalSource { get; private set; }
+        public string[] SearchPaths { get; private set; }
+
+        /// <summary>
+        /// Gets whether <see cref="RecommendedSearchPath"/> indicates that a file was found at that search path.
+        /// </summary>
+        public bool FoundLocal { get; private set; }
+
+        /// <summary>
+        /// When <see cref="FoundLocal"/> is true, the index to <see cref="SearchPaths"/> for the recommended local file.
+        /// </summary>
+        public int RecommendedSearchPath { get; private set; }
 
         /// <summary>
         /// Gets the optional URL to download container or payload.
         /// </summary>
-        public string DownloadSource { get; private set; }
+        public string DownloadUrl { get; private set; }
 
         /// <summary>
-        /// Gets the recommended action from the engine.
+        /// Gets the optional identity of the container that contains the payload being acquired.
         /// </summary>
-        public BOOTSTRAPPER_RESOLVESOURCE_ACTION Recommendation { get; private set; }
+        public string PayloadContainerId { get; private set; }
 
         /// <summary>
-        /// Gets or sets the action to perform.
+        /// Gets or sets the index to <see cref="SearchPaths"/> to use when <see cref="CancellableActionEventArgs{T}.Action"/> is set to <see cref="CacheOperation.Copy"/>.
         /// </summary>
-        public BOOTSTRAPPER_RESOLVESOURCE_ACTION Action { get; set; }
+        public int ChosenSearchPath { get; set; }
     }
 
     /// <summary>
diff --git a/src/WixToolset.Mba.Core/IBootstrapperApplication.cs b/src/WixToolset.Mba.Core/IBootstrapperApplication.cs
index 14cb8fd5..88c65674 100644
--- a/src/WixToolset.Mba.Core/IBootstrapperApplication.cs
+++ b/src/WixToolset.Mba.Core/IBootstrapperApplication.cs
@@ -44,13 +44,10 @@ namespace WixToolset.Mba.Core
         /// <summary>
         /// See <see cref="IDefaultBootstrapperApplication.DetectBegin"/>.
         /// </summary>
-        /// <param name="fInstalled"></param>
-        /// <param name="cPackages"></param>
-        /// <param name="fCancel"></param>
-        /// <returns></returns>
         [PreserveSig]
         [return: MarshalAs(UnmanagedType.I4)]
         int OnDetectBegin(
+            [MarshalAs(UnmanagedType.Bool)] bool fCached,
             [MarshalAs(UnmanagedType.Bool)] bool fInstalled,
             [MarshalAs(UnmanagedType.U4)] int cPackages,
             [MarshalAs(UnmanagedType.Bool)] ref bool fCancel
@@ -540,32 +537,22 @@ namespace WixToolset.Mba.Core
         /// <summary>
         /// See <see cref="IDefaultBootstrapperApplication.CacheAcquireBegin"/>.
         /// </summary>
-        /// <param name="wzPackageOrContainerId"></param>
-        /// <param name="wzPayloadId"></param>
-        /// <param name="operation"></param>
-        /// <param name="wzSource"></param>
-        /// <param name="fCancel"></param>
-        /// <returns></returns>
         [PreserveSig]
         [return: MarshalAs(UnmanagedType.I4)]
         int OnCacheAcquireBegin(
             [MarshalAs(UnmanagedType.LPWStr)] string wzPackageOrContainerId,
             [MarshalAs(UnmanagedType.LPWStr)] string wzPayloadId,
-            [MarshalAs(UnmanagedType.U4)] CacheOperation operation,
             [MarshalAs(UnmanagedType.LPWStr)] string wzSource,
+            [MarshalAs(UnmanagedType.LPWStr)] string wzDownloadUrl,
+            [MarshalAs(UnmanagedType.LPWStr)] string wzPayloadContainerId,
+            [MarshalAs(UnmanagedType.U4)] CacheOperation recommendation,
+            [MarshalAs(UnmanagedType.I4)] ref CacheOperation action,
             [MarshalAs(UnmanagedType.Bool)] ref bool fCancel
             );
 
         /// <summary>
         /// See <see cref="IDefaultBootstrapperApplication.CacheAcquireProgress"/>.
         /// </summary>
-        /// <param name="wzPackageOrContainerId"></param>
-        /// <param name="wzPayloadId"></param>
-        /// <param name="dw64Progress"></param>
-        /// <param name="dw64Total"></param>
-        /// <param name="dwOverallPercentage"></param>
-        /// <param name="fCancel"></param>
-        /// <returns></returns>
         [PreserveSig]
         [return: MarshalAs(UnmanagedType.I4)]
         int OnCacheAcquireProgress(
@@ -578,37 +565,28 @@ namespace WixToolset.Mba.Core
             );
 
         /// <summary>
-        /// See <see cref="IDefaultBootstrapperApplication.ResolveSource"/>.
+        /// See <see cref="IDefaultBootstrapperApplication.CacheAcquireResolving"/>.
         /// </summary>
-        /// <param name="wzPackageOrContainerId"></param>
-        /// <param name="wzPayloadId"></param>
-        /// <param name="wzLocalSource"></param>
-        /// <param name="wzDownloadSource"></param>
-        /// <param name="recommendation"></param>
-        /// <param name="action"></param>
-        /// <param name="fCancel"></param>
-        /// <returns></returns>
         [PreserveSig]
         [return: MarshalAs(UnmanagedType.I4)]
-        int OnResolveSource(
+        int OnCacheAcquireResolving(
             [MarshalAs(UnmanagedType.LPWStr)] string wzPackageOrContainerId,
             [MarshalAs(UnmanagedType.LPWStr)] string wzPayloadId,
-            [MarshalAs(UnmanagedType.LPWStr)] string wzLocalSource,
-            [MarshalAs(UnmanagedType.LPWStr)] string wzDownloadSource,
-            BOOTSTRAPPER_RESOLVESOURCE_ACTION recommendation,
-            ref BOOTSTRAPPER_RESOLVESOURCE_ACTION action,
+            [MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 3, ArraySubType = UnmanagedType.LPWStr), In] string[] searchPaths,
+            [MarshalAs(UnmanagedType.U4)] int cSearchPaths,
+            [MarshalAs(UnmanagedType.Bool)] bool fFoundLocal,
+            [MarshalAs(UnmanagedType.U4)] int dwRecommendedSearchPath,
+            [MarshalAs(UnmanagedType.LPWStr)] string wzDownloadUrl,
+            [MarshalAs(UnmanagedType.LPWStr)] string wzPayloadContainerId,
+            [MarshalAs(UnmanagedType.I4)] CacheResolveOperation recommendation,
+            [MarshalAs(UnmanagedType.U4)] ref int dwChosenSearchPath,
+            [MarshalAs(UnmanagedType.I4)] ref CacheResolveOperation action,
             [MarshalAs(UnmanagedType.Bool)] ref bool fCancel
             );
 
         /// <summary>
         /// See <see cref="IDefaultBootstrapperApplication.CacheAcquireComplete"/>.
         /// </summary>
-        /// <param name="wzPackageOrContainerId"></param>
-        /// <param name="wzPayloadId"></param>
-        /// <param name="hrStatus"></param>
-        /// <param name="recommendation"></param>
-        /// <param name="pAction"></param>
-        /// <returns></returns>
         [PreserveSig]
         [return: MarshalAs(UnmanagedType.I4)]
         int OnCacheAcquireComplete(
@@ -1419,19 +1397,55 @@ namespace WixToolset.Mba.Core
     public enum CacheOperation
     {
         /// <summary>
-        /// Container or payload is being copied.
+        /// There is no source available.
+        /// </summary>
+        None,
+
+        /// <summary>
+        /// Copy the payload or container from the chosen local source.
         /// </summary>
         Copy,
 
         /// <summary>
-        /// Container or payload is being downloaded.
+        /// Download the payload or container using the download URL.
         /// </summary>
         Download,
 
         /// <summary>
-        /// Container or payload is being extracted.
+        /// Extract the payload from the container.
+        /// </summary>
+        Extract,
+    }
+
+    /// <summary>
+    /// The source to be used to acquire a container or payload.
+    /// </summary>
+    public enum CacheResolveOperation
+    {
+        /// <summary>
+        /// There is no source available.
+        /// </summary>
+        None,
+
+        /// <summary>
+        /// Copy the payload or container from the chosen local source.
         /// </summary>
-        Extract
+        Local,
+
+        /// <summary>
+        /// Download the payload or container from the download URL.
+        /// </summary>
+        Download,
+
+        /// <summary>
+        /// Extract the payload from the container.
+        /// </summary>
+        Container,
+
+        /// <summary>
+        /// Look again for the payload or container locally.
+        /// </summary>
+        Retry,
     }
 
     /// <summary>
@@ -1637,7 +1651,7 @@ namespace WixToolset.Mba.Core
     }
 
     /// <summary>
-    /// The available actions for <see cref="IDefaultBootstrapperApplication.ResolveSource"/>.
+    /// The available actions for <see cref="IDefaultBootstrapperApplication.CacheAcquireResolving"/>.
     /// </summary>
     public enum BOOTSTRAPPER_RESOLVESOURCE_ACTION
     {
diff --git a/src/WixToolset.Mba.Core/IDefaultBootstrapperApplication.cs b/src/WixToolset.Mba.Core/IDefaultBootstrapperApplication.cs
index 269d4955..03f94d37 100644
--- a/src/WixToolset.Mba.Core/IDefaultBootstrapperApplication.cs
+++ b/src/WixToolset.Mba.Core/IDefaultBootstrapperApplication.cs
@@ -30,12 +30,16 @@ namespace WixToolset.Mba.Core
         event EventHandler<BeginMsiTransactionCompleteEventArgs> BeginMsiTransactionComplete;
 
         /// <summary>
-        /// Fired when the engine has begun acquiring the installation sources.
+        /// Fired when the engine has begun acquiring the payload or container.
+        /// The BA can change the source using <see cref="IEngine.SetLocalSource(string, string, string)"/>
+        /// or <see cref="IEngine.SetDownloadSource(string, string, string, string, string)"/>.
         /// </summary>
         event EventHandler<CacheAcquireBeginEventArgs> CacheAcquireBegin;
 
         /// <summary>
-        /// Fired when the engine has completed the acquisition of the installation sources.
+        /// Fired when the engine has completed the acquisition of the payload or container.
+        /// The BA can change the source using <see cref="IEngine.SetLocalSource(string, string, string)"/>
+        /// or <see cref="IEngine.SetDownloadSource(string, string, string, string, string)"/>.
         /// </summary>
         event EventHandler<CacheAcquireCompleteEventArgs> CacheAcquireComplete;
 
@@ -45,6 +49,11 @@ namespace WixToolset.Mba.Core
         event EventHandler<CacheAcquireProgressEventArgs> CacheAcquireProgress;
 
         /// <summary>
+        /// Fired by the engine to allow the BA to override the acquisition action.
+        /// </summary>
+        event EventHandler<CacheAcquireResolvingEventArgs> CacheAcquireResolving;
+
+        /// <summary>
         /// Fired when the engine has begun caching the installation sources.
         /// </summary>
         event EventHandler<CacheBeginEventArgs> CacheBegin;
@@ -285,12 +294,6 @@ namespace WixToolset.Mba.Core
         event EventHandler<RegisterCompleteEventArgs> RegisterComplete;
 
         /// <summary>
-        /// Fired by the engine to allow the BA to change the source
-        /// using <see cref="IEngine.SetLocalSource(string, string, string)"/> or <see cref="IEngine.SetDownloadSource(string, string, string, string, string)"/>.
-        /// </summary>
-        event EventHandler<ResolveSourceEventArgs> ResolveSource;
-
-        /// <summary>
         /// Fired when the engine is about to rollback an MSI transaction.
         /// </summary>
         event EventHandler<RollbackMsiTransactionBeginEventArgs> RollbackMsiTransactionBegin;