@joebigelow / wix-1
Code Commits Issues Pulls Sessions CI/CD
main
main
cs 230 lines 10.5 KB
Raw
1 // Copyright (c) .NET Foundation and contributors. All rights reserved. Licensed under the Microsoft Reciprocal License. See LICENSE.TXT file in the project root for full license information.
2
3 namespace WixToolset.BootstrapperApplicationApi
4 {
5 using System;
6 using System.ComponentModel;
7 using System.Security;
8
9 /// <summary>
10 /// High level abstraction over the <see cref="IBootstrapperEngine"/> interface.
11 /// </summary>
12 public interface IEngine
13 {
14 /// <summary>
15 /// Gets the number of packages in the bundle.
16 /// </summary>
17 int PackageCount { get; }
18
19 /// <summary>
20 /// Install the packages.
21 /// </summary>
22 /// <param name="hwndParent">The parent window for the installation user interface.</param>
23 void Apply(IntPtr hwndParent);
24
25 /// <summary>
26 /// Close the splash screen if it is still open. Does nothing if the splash screen is not or
27 /// never was opened.
28 /// </summary>
29 void CloseSplashScreen();
30
31 /// <returns>0 if equal, 1 if version1 &gt; version2, -1 if version1 &lt; version2</returns>
32 int CompareVersions(string version1, string version2);
33
34 /// <summary>
35 /// Checks if a variable exists in the engine.
36 /// </summary>
37 /// <param name="name">The name of the variable.</param>
38 /// <returns>Whether the variable exists.</returns>
39 bool ContainsVariable(string name);
40
41 /// <summary>
42 /// Determine if all installation conditions are fulfilled.
43 /// </summary>
44 void Detect();
45
46 /// <summary>
47 /// Determine if all installation conditions are fulfilled.
48 /// </summary>
49 /// <param name="hwndParent">The parent window for the installation user interface.</param>
50 void Detect(IntPtr hwndParent);
51
52 /// <summary>
53 /// Elevate the install.
54 /// </summary>
55 /// <param name="hwndParent">The parent window of the elevation dialog.</param>
56 /// <returns>true if elevation succeeded; otherwise, false if the user cancelled.</returns>
57 /// <exception cref="Win32Exception">A Win32 error occurred.</exception>
58 bool Elevate(IntPtr hwndParent);
59
60 /// <summary>
61 /// Escapes the input string.
62 /// </summary>
63 /// <param name="input">The string to escape.</param>
64 /// <returns>The escaped string.</returns>
65 /// <exception cref="Win32Exception">A Win32 error occurred.</exception>
66 string EscapeString(string input);
67
68 /// <summary>
69 /// Evaluates the <paramref name="condition"/> string.
70 /// </summary>
71 /// <param name="condition">The string representing the condition to evaluate.</param>
72 /// <returns>Whether the condition evaluated to true or false.</returns>
73 bool EvaluateCondition(string condition);
74
75 /// <summary>
76 /// Formats the input string.
77 /// </summary>
78 /// <param name="format">The string to format.</param>
79 /// <returns>The formatted string.</returns>
80 /// <exception cref="Win32Exception">A Win32 error occurred.</exception>
81 string FormatString(string format);
82
83 /// <summary>
84 /// Gets numeric variables for the engine.
85 /// </summary>
86 /// <param name="name">The name of the variable.</param>
87 long GetVariableNumeric(string name);
88
89 /// <summary>
90 /// Gets string variables for the engine using SecureStrings.
91 /// </summary>
92 /// <param name="name">The name of the variable.</param>
93 SecureString GetVariableSecureString(string name);
94
95 /// <summary>
96 /// Gets string variables for the engine.
97 /// </summary>
98 /// <param name="name">The name of the variable.</param>
99 string GetVariableString(string name);
100
101 /// <summary>
102 /// Gets <see cref="Version"/> variables for the engine.
103 /// </summary>
104 /// <param name="name">The name of the variable.</param>
105 string GetVariableVersion(string name);
106
107 /// <summary>
108 /// Gets persisted variables from a related bundle.
109 /// </summary>
110 /// <param name="bundleId">The BundleId of the related bundle.</param>
111 /// <param name="name">The name of the variable.</param>
112 string GetRelatedBundleVariable(string bundleId, string name);
113
114 /// <summary>
115 /// Launches a preapproved executable elevated. As long as the engine already elevated, there will be no UAC prompt.
116 /// </summary>
117 /// <param name="hwndParent">The parent window of the elevation dialog (if the engine hasn't elevated yet).</param>
118 /// <param name="approvedExeForElevationId">Id of the ApprovedExeForElevation element specified when the bundle was authored.</param>
119 /// <param name="arguments">Optional arguments.</param>
120 void LaunchApprovedExe(IntPtr hwndParent, string approvedExeForElevationId, string arguments);
121
122 /// <summary>
123 /// Launches a preapproved executable elevated. As long as the engine already elevated, there will be no UAC prompt.
124 /// </summary>
125 /// <param name="hwndParent">The parent window of the elevation dialog (if the engine hasn't elevated yet).</param>
126 /// <param name="approvedExeForElevationId">Id of the ApprovedExeForElevation element specified when the bundle was authored.</param>
127 /// <param name="arguments">Optional arguments.</param>
128 /// <param name="waitForInputIdleTimeout">Timeout in milliseconds. When set to something other than zero, the engine will call WaitForInputIdle for the new process with this timeout before calling OnLaunchApprovedExeComplete.</param>
129 void LaunchApprovedExe(IntPtr hwndParent, string approvedExeForElevationId, string arguments, int waitForInputIdleTimeout);
130
131 /// <summary>
132 /// Logs the <paramref name="message"/>.
133 /// </summary>
134 /// <param name="level">The logging level.</param>
135 /// <param name="message">The message to log.</param>
136 void Log(LogLevel level, string message);
137
138 /// <summary>
139 /// Determine the installation sequencing and costing.
140 /// </summary>
141 /// <param name="action">The action to perform when planning.</param>
142 void Plan(LaunchAction action);
143
144 /// <summary>
145 /// Set the update information for a bundle.
146 /// </summary>
147 /// <param name="localSource">Optional local source path for the update. Default is "update\[OriginalNameOfBundle].exe".</param>
148 /// <param name="downloadSource">Optional download source for the update.</param>
149 /// <param name="size">Size of the expected update.</param>
150 /// <param name="hashType">Type of the hash expected on the update.</param>
151 /// <param name="hash">Optional hash expected for the update.</param>
152 /// <param name="updatePackageId">Optional package id for the update.</param>
153 void SetUpdate(string localSource, string downloadSource, long size, UpdateHashType hashType, string hash, string updatePackageId);
154
155 /// <summary>
156 /// Sets the URL to the update feed.
157 /// </summary>
158 /// <param name="url">URL of the update feed.</param>
159 void SetUpdateSource(string url);
160
161 /// <summary>
162 /// Set the local source for a package or container.
163 /// </summary>
164 /// <param name="packageOrContainerId">The id that uniquely identifies the package or container.</param>
165 /// <param name="payloadId">The id that uniquely identifies the payload.</param>
166 /// <param name="path">The new source path.</param>
167 void SetLocalSource(string packageOrContainerId, string payloadId, string path);
168
169 /// <summary>
170 /// Set the new download URL for a package or container.
171 /// </summary>
172 /// <param name="packageOrContainerId">The id that uniquely identifies the package or container.</param>
173 /// <param name="payloadId">The id that uniquely identifies the payload.</param>
174 /// <param name="url">The new url.</param>
175 /// <param name="user">The user name for proxy authentication.</param>
176 /// <param name="password">The password for proxy authentication.</param>
177 void SetDownloadSource(string packageOrContainerId, string payloadId, string url, string user, string password);
178
179 /// <summary>
180 /// Sets numeric variables for the engine.
181 /// </summary>
182 /// <param name="name">The name of the variable.</param>
183 /// <param name="value">The value to set.</param>
184 void SetVariableNumeric(string name, long value);
185
186 /// <summary>
187 /// Sets string variables for the engine using SecureStrings.
188 /// </summary>
189 /// <param name="name">The name of the variable.</param>
190 /// <param name="value">The value to set.</param>
191 /// <param name="formatted">False if the value is a literal string.</param>
192 void SetVariableString(string name, SecureString value, bool formatted);
193
194 /// <summary>
195 /// Sets string variables for the engine.
196 /// </summary>
197 /// <param name="name">The name of the variable.</param>
198 /// <param name="value">The value to set.</param>
199 /// <param name="formatted">False if the value is a literal string.</param>
200 void SetVariableString(string name, string value, bool formatted);
201
202 /// <summary>
203 /// Sets version variables for the engine.
204 /// </summary>
205 /// <param name="name">The name of the variable.</param>
206 /// <param name="value">The value to set.</param>
207 void SetVariableVersion(string name, string value);
208
209 /// <summary>
210 /// Sends error message when embedded.
211 /// </summary>
212 /// <param name="errorCode">Error code.</param>
213 /// <param name="message">Error message.</param>
214 /// <param name="uiHint">UI buttons to show on error dialog.</param>
215 int SendEmbeddedError(int errorCode, string message, int uiHint);
216
217 /// <summary>
218 /// Sends progress percentages when embedded.
219 /// </summary>
220 /// <param name="progressPercentage">Percentage completed thus far.</param>
221 /// <param name="overallPercentage">Overall percentage completed.</param>
222 int SendEmbeddedProgress(int progressPercentage, int overallPercentage);
223
224 /// <summary>
225 /// Shuts down the engine.
226 /// </summary>
227 /// <param name="exitCode">Exit code indicating reason for shut down.</param>
228 void Quit(int exitCode);
229 }
230 }