contrib/llvm-project/clang/lib/Driver/ToolChains/MSVCSetupApi.h

   1 // <copyright file="Program.cpp" company="Microsoft Corporation">
   2 // Copyright (C) Microsoft Corporation. All rights reserved.
   3 // Licensed under the MIT license.
   4 // </copyright>
   5 // <license>
   6 // The MIT License (MIT)
   7 //
   8 // Copyright (C) Microsoft Corporation. All rights reserved.
   9 //
  10 // Permission is hereby granted, free of charge, to any person obtaining
  11 // a copy of this software and associated documentation files (the "Software"),
  12 // to deal in the Software without restriction, including without limitation the
  13 // rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  14 // sell copies of the Software, and to permit persons to whom the Software is
  15 // furnished to do so, subject to the following conditions:
  16 //
  17 // The above copyright notice and this permission notice shall be included in
  18 // all copies or substantial portions of the Software.
  19 //
  20 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  21 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  22 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  23 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  24 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  25 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  26 // SOFTWARE.
  27 // </license>
  28
  29 #pragma once
  30
  31 // Constants
  32 //
  33 #ifndef E_NOTFOUND
  34 #define E_NOTFOUND HRESULT_FROM_WIN32(ERROR_NOT_FOUND)
  35 #endif
  36
  37 #ifndef E_FILENOTFOUND
  38 #define E_FILENOTFOUND HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)
  39 #endif
  40
  41 // Enumerations
  42 //
  43 /// <summary>
  44 /// The state of an instance.
  45 /// </summary>
  46 enum InstanceState : unsigned {
  47   /// <summary>
  48   /// The instance state has not been determined.
  49   /// </summary>
  50   eNone = 0,
  51
  52   /// <summary>
  53   /// The instance installation path exists.
  54   /// </summary>
  55   eLocal = 1,
  56
  57   /// <summary>
  58   /// A product is registered to the instance.
  59   /// </summary>
  60   eRegistered = 2,
  61
  62   /// <summary>
  63   /// No reboot is required for the instance.
  64   /// </summary>
  65   eNoRebootRequired = 4,
  66
  67   /// <summary>
  68   /// The instance represents a complete install.
  69   /// </summary>
  70   eComplete = MAXUINT,
  71 };
  72
  73 // Forward interface declarations
  74 //
  75 #ifndef __ISetupInstance_FWD_DEFINED__
  76 #define __ISetupInstance_FWD_DEFINED__
  77 typedef struct ISetupInstance ISetupInstance;
  78 #endif
  79
  80 #ifndef __ISetupInstance2_FWD_DEFINED__
  81 #define __ISetupInstance2_FWD_DEFINED__
  82 typedef struct ISetupInstance2 ISetupInstance2;
  83 #endif
  84
  85 #ifndef __IEnumSetupInstances_FWD_DEFINED__
  86 #define __IEnumSetupInstances_FWD_DEFINED__
  87 typedef struct IEnumSetupInstances IEnumSetupInstances;
  88 #endif
  89
  90 #ifndef __ISetupConfiguration_FWD_DEFINED__
  91 #define __ISetupConfiguration_FWD_DEFINED__
  92 typedef struct ISetupConfiguration ISetupConfiguration;
  93 #endif
  94
  95 #ifndef __ISetupConfiguration2_FWD_DEFINED__
  96 #define __ISetupConfiguration2_FWD_DEFINED__
  97 typedef struct ISetupConfiguration2 ISetupConfiguration2;
  98 #endif
  99
 100 #ifndef __ISetupPackageReference_FWD_DEFINED__
 101 #define __ISetupPackageReference_FWD_DEFINED__
 102 typedef struct ISetupPackageReference ISetupPackageReference;
 103 #endif
 104
 105 #ifndef __ISetupHelper_FWD_DEFINED__
 106 #define __ISetupHelper_FWD_DEFINED__
 107 typedef struct ISetupHelper ISetupHelper;
 108 #endif
 109
 110 // Forward class declarations
 111 //
 112 #ifndef __SetupConfiguration_FWD_DEFINED__
 113 #define __SetupConfiguration_FWD_DEFINED__
 114
 115 #ifdef __cplusplus
 116 typedef class SetupConfiguration SetupConfiguration;
 117 #endif
 118
 119 #endif
 120
 121 #ifdef __cplusplus
 122 extern "C" {
 123 #endif
 124
 125 // Interface definitions
 126 //
 127 EXTERN_C const IID IID_ISetupInstance;
 128
 129 #if defined(__cplusplus) && !defined(CINTERFACE)
 130 /// <summary>
 131 /// Information about an instance of a product.
 132 /// </summary>
 133 struct DECLSPEC_UUID("B41463C3-8866-43B5-BC33-2B0676F7F42E")
 134     DECLSPEC_NOVTABLE ISetupInstance : public IUnknown {
 135   /// <summary>
 136   /// Gets the instance identifier (should match the name of the parent instance
 137   /// directory).
 138   /// </summary>
 139   /// <param name="pbstrInstanceId">The instance identifier.</param>
 140   /// <returns>Standard HRESULT indicating success or failure, including
 141   /// E_FILENOTFOUND if the instance state does not exist.</returns>
 142   STDMETHOD(GetInstanceId)(_Out_ BSTR *pbstrInstanceId) = 0;
 143
 144   /// <summary>
 145   /// Gets the local date and time when the installation was originally
 146   /// installed.
 147   /// </summary>
 148   /// <param name="pInstallDate">The local date and time when the installation
 149   /// was originally installed.</param>
 150   /// <returns>Standard HRESULT indicating success or failure, including
 151   /// E_FILENOTFOUND if the instance state does not exist and E_NOTFOUND if the
 152   /// property is not defined.</returns>
 153   STDMETHOD(GetInstallDate)(_Out_ LPFILETIME pInstallDate) = 0;
 154
 155   /// <summary>
 156   /// Gets the unique name of the installation, often indicating the branch and
 157   /// other information used for telemetry.
 158   /// </summary>
 159   /// <param name="pbstrInstallationName">The unique name of the installation,
 160   /// often indicating the branch and other information used for
 161   /// telemetry.</param>
 162   /// <returns>Standard HRESULT indicating success or failure, including
 163   /// E_FILENOTFOUND if the instance state does not exist and E_NOTFOUND if the
 164   /// property is not defined.</returns>
 165   STDMETHOD(GetInstallationName)(_Out_ BSTR *pbstrInstallationName) = 0;
 166
 167   /// <summary>
 168   /// Gets the path to the installation root of the product.
 169   /// </summary>
 170   /// <param name="pbstrInstallationPath">The path to the installation root of
 171   /// the product.</param>
 172   /// <returns>Standard HRESULT indicating success or failure, including
 173   /// E_FILENOTFOUND if the instance state does not exist and E_NOTFOUND if the
 174   /// property is not defined.</returns>
 175   STDMETHOD(GetInstallationPath)(_Out_ BSTR *pbstrInstallationPath) = 0;
 176
 177   /// <summary>
 178   /// Gets the version of the product installed in this instance.
 179   /// </summary>
 180   /// <param name="pbstrInstallationVersion">The version of the product
 181   /// installed in this instance.</param>
 182   /// <returns>Standard HRESULT indicating success or failure, including
 183   /// E_FILENOTFOUND if the instance state does not exist and E_NOTFOUND if the
 184   /// property is not defined.</returns>
 185   STDMETHOD(GetInstallationVersion)(_Out_ BSTR *pbstrInstallationVersion) = 0;
 186
 187   /// <summary>
 188   /// Gets the display name (title) of the product installed in this instance.
 189   /// </summary>
 190   /// <param name="lcid">The LCID for the display name.</param>
 191   /// <param name="pbstrDisplayName">The display name (title) of the product
 192   /// installed in this instance.</param>
 193   /// <returns>Standard HRESULT indicating success or failure, including
 194   /// E_FILENOTFOUND if the instance state does not exist and E_NOTFOUND if the
 195   /// property is not defined.</returns>
 196   STDMETHOD(GetDisplayName)(_In_ LCID lcid, _Out_ BSTR *pbstrDisplayName) = 0;
 197
 198   /// <summary>
 199   /// Gets the description of the product installed in this instance.
 200   /// </summary>
 201   /// <param name="lcid">The LCID for the description.</param>
 202   /// <param name="pbstrDescription">The description of the product installed in
 203   /// this instance.</param>
 204   /// <returns>Standard HRESULT indicating success or failure, including
 205   /// E_FILENOTFOUND if the instance state does not exist and E_NOTFOUND if the
 206   /// property is not defined.</returns>
 207   STDMETHOD(GetDescription)(_In_ LCID lcid, _Out_ BSTR *pbstrDescription) = 0;
 208
 209   /// <summary>
 210   /// Resolves the optional relative path to the root path of the instance.
 211   /// </summary>
 212   /// <param name="pwszRelativePath">A relative path within the instance to
 213   /// resolve, or NULL to get the root path.</param>
 214   /// <param name="pbstrAbsolutePath">The full path to the optional relative
 215   /// path within the instance. If the relative path is NULL, the root path will
 216   /// always terminate in a backslash.</param>
 217   /// <returns>Standard HRESULT indicating success or failure, including
 218   /// E_FILENOTFOUND if the instance state does not exist and E_NOTFOUND if the
 219   /// property is not defined.</returns>
 220   STDMETHOD(ResolvePath)
 221   (_In_opt_z_ LPCOLESTR pwszRelativePath, _Out_ BSTR *pbstrAbsolutePath) = 0;
 222 };
 223 #endif
 224
 225 EXTERN_C const IID IID_ISetupInstance2;
 226
 227 #if defined(__cplusplus) && !defined(CINTERFACE)
 228 /// <summary>
 229 /// Information about an instance of a product.
 230 /// </summary>
 231 struct DECLSPEC_UUID("89143C9A-05AF-49B0-B717-72E218A2185C")
 232     DECLSPEC_NOVTABLE ISetupInstance2 : public ISetupInstance {
 233   /// <summary>
 234   /// Gets the state of the instance.
 235   /// </summary>
 236   /// <param name="pState">The state of the instance.</param>
 237   /// <returns>Standard HRESULT indicating success or failure, including
 238   /// E_FILENOTFOUND if the instance state does not exist.</returns>
 239   STDMETHOD(GetState)(_Out_ InstanceState *pState) = 0;
 240
 241   /// <summary>
 242   /// Gets an array of package references registered to the instance.
 243   /// </summary>
 244   /// <param name="ppsaPackages">Pointer to an array of <see
 245   /// cref="ISetupPackageReference"/>.</param>
 246   /// <returns>Standard HRESULT indicating success or failure, including
 247   /// E_FILENOTFOUND if the instance state does not exist and E_NOTFOUND if the
 248   /// packages property is not defined.</returns>
 249   STDMETHOD(GetPackages)(_Out_ LPSAFEARRAY *ppsaPackages) = 0;
 250
 251   /// <summary>
 252   /// Gets a pointer to the <see cref="ISetupPackageReference"/> that represents
 253   /// the registered product.
 254   /// </summary>
 255   /// <param name="ppPackage">Pointer to an instance of <see
 256   /// cref="ISetupPackageReference"/>. This may be NULL if <see
 257   /// cref="GetState"/> does not return <see cref="eComplete"/>.</param>
 258   /// <returns>Standard HRESULT indicating success or failure, including
 259   /// E_FILENOTFOUND if the instance state does not exist and E_NOTFOUND if the
 260   /// packages property is not defined.</returns>
 261   STDMETHOD(GetProduct)
 262   (_Outptr_result_maybenull_ ISetupPackageReference **ppPackage) = 0;
 263
 264   /// <summary>
 265   /// Gets the relative path to the product application, if available.
 266   /// </summary>
 267   /// <param name="pbstrProductPath">The relative path to the product
 268   /// application, if available.</param>
 269   /// <returns>Standard HRESULT indicating success or failure, including
 270   /// E_FILENOTFOUND if the instance state does not exist.</returns>
 271   STDMETHOD(GetProductPath)
 272   (_Outptr_result_maybenull_ BSTR *pbstrProductPath) = 0;
 273 };
 274 #endif
 275
 276 EXTERN_C const IID IID_IEnumSetupInstances;
 277
 278 #if defined(__cplusplus) && !defined(CINTERFACE)
 279 /// <summary>
 280 /// A enumerator of installed <see cref="ISetupInstance"/> objects.
 281 /// </summary>
 282 struct DECLSPEC_UUID("6380BCFF-41D3-4B2E-8B2E-BF8A6810C848")
 283     DECLSPEC_NOVTABLE IEnumSetupInstances : public IUnknown {
 284   /// <summary>
 285   /// Retrieves the next set of product instances in the enumeration sequence.
 286   /// </summary>
 287   /// <param name="celt">The number of product instances to retrieve.</param>
 288   /// <param name="rgelt">A pointer to an array of <see
 289   /// cref="ISetupInstance"/>.</param>
 290   /// <param name="pceltFetched">A pointer to the number of product instances
 291   /// retrieved. If celt is 1 this parameter may be NULL.</param>
 292   /// <returns>S_OK if the number of elements were fetched, S_FALSE if nothing
 293   /// was fetched (at end of enumeration), E_INVALIDARG if celt is greater than
 294   /// 1 and pceltFetched is NULL, or E_OUTOFMEMORY if an <see
 295   /// cref="ISetupInstance"/> could not be allocated.</returns>
 296   STDMETHOD(Next)
 297   (_In_ ULONG celt, _Out_writes_to_(celt, *pceltFetched) ISetupInstance **rgelt,
 298    _Out_opt_ _Deref_out_range_(0, celt) ULONG *pceltFetched) = 0;
 299
 300   /// <summary>
 301   /// Skips the next set of product instances in the enumeration sequence.
 302   /// </summary>
 303   /// <param name="celt">The number of product instances to skip.</param>
 304   /// <returns>S_OK if the number of elements could be skipped; otherwise,
 305   /// S_FALSE;</returns>
 306   STDMETHOD(Skip)(_In_ ULONG celt) = 0;
 307
 308   /// <summary>
 309   /// Resets the enumeration sequence to the beginning.
 310   /// </summary>
 311   /// <returns>Always returns S_OK;</returns>
 312   STDMETHOD(Reset)(void) = 0;
 313
 314   /// <summary>
 315   /// Creates a new enumeration object in the same state as the current
 316   /// enumeration object: the new object points to the same place in the
 317   /// enumeration sequence.
 318   /// </summary>
 319   /// <param name="ppenum">A pointer to a pointer to a new <see
 320   /// cref="IEnumSetupInstances"/> interface. If the method fails, this
 321   /// parameter is undefined.</param>
 322   /// <returns>S_OK if a clone was returned; otherwise, E_OUTOFMEMORY.</returns>
 323   STDMETHOD(Clone)(_Deref_out_opt_ IEnumSetupInstances **ppenum) = 0;
 324 };
 325 #endif
 326
 327 EXTERN_C const IID IID_ISetupConfiguration;
 328
 329 #if defined(__cplusplus) && !defined(CINTERFACE)
 330 /// <summary>
 331 /// Gets information about product instances set up on the machine.
 332 /// </summary>
 333 struct DECLSPEC_UUID("42843719-DB4C-46C2-8E7C-64F1816EFD5B")
 334     DECLSPEC_NOVTABLE ISetupConfiguration : public IUnknown {
 335   /// <summary>
 336   /// Enumerates all completed product instances installed.
 337   /// </summary>
 338   /// <param name="ppEnumInstances">An enumeration of completed, installed
 339   /// product instances.</param>
 340   /// <returns>Standard HRESULT indicating success or failure.</returns>
 341   STDMETHOD(EnumInstances)(_Out_ IEnumSetupInstances **ppEnumInstances) = 0;
 342
 343   /// <summary>
 344   /// Gets the instance for the current process path.
 345   /// </summary>
 346   /// <param name="ppInstance">The instance for the current process
 347   /// path.</param>
 348   /// <returns>The instance for the current process path, or E_NOTFOUND if not
 349   /// found.</returns>
 350   STDMETHOD(GetInstanceForCurrentProcess)
 351   (_Out_ ISetupInstance **ppInstance) = 0;
 352
 353   /// <summary>
 354   /// Gets the instance for the given path.
 355   /// </summary>
 356   /// <param name="ppInstance">The instance for the given path.</param>
 357   /// <returns>The instance for the given path, or E_NOTFOUND if not
 358   /// found.</returns>
 359   STDMETHOD(GetInstanceForPath)
 360   (_In_z_ LPCWSTR wzPath, _Out_ ISetupInstance **ppInstance) = 0;
 361 };
 362 #endif
 363
 364 EXTERN_C const IID IID_ISetupConfiguration2;
 365
 366 #if defined(__cplusplus) && !defined(CINTERFACE)
 367 /// <summary>
 368 /// Gets information about product instances.
 369 /// </summary>
 370 struct DECLSPEC_UUID("26AAB78C-4A60-49D6-AF3B-3C35BC93365D")
 371     DECLSPEC_NOVTABLE ISetupConfiguration2 : public ISetupConfiguration {
 372   /// <summary>
 373   /// Enumerates all product instances.
 374   /// </summary>
 375   /// <param name="ppEnumInstances">An enumeration of all product
 376   /// instances.</param>
 377   /// <returns>Standard HRESULT indicating success or failure.</returns>
 378   STDMETHOD(EnumAllInstances)(_Out_ IEnumSetupInstances **ppEnumInstances) = 0;
 379 };
 380 #endif
 381
 382 EXTERN_C const IID IID_ISetupPackageReference;
 383
 384 #if defined(__cplusplus) && !defined(CINTERFACE)
 385 /// <summary>
 386 /// A reference to a package.
 387 /// </summary>
 388 struct DECLSPEC_UUID("da8d8a16-b2b6-4487-a2f1-594ccccd6bf5")
 389     DECLSPEC_NOVTABLE ISetupPackageReference : public IUnknown {
 390   /// <summary>
 391   /// Gets the general package identifier.
 392   /// </summary>
 393   /// <param name="pbstrId">The general package identifier.</param>
 394   /// <returns>Standard HRESULT indicating success or failure.</returns>
 395   STDMETHOD(GetId)(_Out_ BSTR *pbstrId) = 0;
 396
 397   /// <summary>
 398   /// Gets the version of the package.
 399   /// </summary>
 400   /// <param name="pbstrVersion">The version of the package.</param>
 401   /// <returns>Standard HRESULT indicating success or failure.</returns>
 402   STDMETHOD(GetVersion)(_Out_ BSTR *pbstrVersion) = 0;
 403
 404   /// <summary>
 405   /// Gets the target process architecture of the package.
 406   /// </summary>
 407   /// <param name="pbstrChip">The target process architecture of the
 408   /// package.</param>
 409   /// <returns>Standard HRESULT indicating success or failure.</returns>
 410   STDMETHOD(GetChip)(_Out_ BSTR *pbstrChip) = 0;
 411
 412   /// <summary>
 413   /// Gets the language and optional region identifier.
 414   /// </summary>
 415   /// <param name="pbstrLanguage">The language and optional region
 416   /// identifier.</param>
 417   /// <returns>Standard HRESULT indicating success or failure.</returns>
 418   STDMETHOD(GetLanguage)(_Out_ BSTR *pbstrLanguage) = 0;
 419
 420   /// <summary>
 421   /// Gets the build branch of the package.
 422   /// </summary>
 423   /// <param name="pbstrBranch">The build branch of the package.</param>
 424   /// <returns>Standard HRESULT indicating success or failure.</returns>
 425   STDMETHOD(GetBranch)(_Out_ BSTR *pbstrBranch) = 0;
 426
 427   /// <summary>
 428   /// Gets the type of the package.
 429   /// </summary>
 430   /// <param name="pbstrType">The type of the package.</param>
 431   /// <returns>Standard HRESULT indicating success or failure.</returns>
 432   STDMETHOD(GetType)(_Out_ BSTR *pbstrType) = 0;
 433
 434   /// <summary>
 435   /// Gets the unique identifier consisting of all defined tokens.
 436   /// </summary>
 437   /// <param name="pbstrUniqueId">The unique identifier consisting of all
 438   /// defined tokens.</param>
 439   /// <returns>Standard HRESULT indicating success or failure, including
 440   /// E_UNEXPECTED if no Id was defined (required).</returns>
 441   STDMETHOD(GetUniqueId)(_Out_ BSTR *pbstrUniqueId) = 0;
 442 };
 443 #endif
 444
 445 EXTERN_C const IID IID_ISetupHelper;
 446
 447 #if defined(__cplusplus) && !defined(CINTERFACE)
 448 /// <summary>
 449 /// Helper functions.
 450 /// </summary>
 451 /// <remarks>
 452 /// You can query for this interface from the <see cref="SetupConfiguration"/>
 453 /// class.
 454 /// </remarks>
 455 struct DECLSPEC_UUID("42b21b78-6192-463e-87bf-d577838f1d5c")
 456     DECLSPEC_NOVTABLE ISetupHelper : public IUnknown {
 457   /// <summary>
 458   /// Parses a dotted quad version string into a 64-bit unsigned integer.
 459   /// </summary>
 460   /// <param name="pwszVersion">The dotted quad version string to parse, e.g.
 461   /// 1.2.3.4.</param>
 462   /// <param name="pullVersion">A 64-bit unsigned integer representing the
 463   /// version. You can compare this to other versions.</param>
 464   /// <returns>Standard HRESULT indicating success or failure.</returns>
 465   STDMETHOD(ParseVersion)
 466   (_In_ LPCOLESTR pwszVersion, _Out_ PULONGLONG pullVersion) = 0;
 467
 468   /// <summary>
 469   /// Parses a dotted quad version string into a 64-bit unsigned integer.
 470   /// </summary>
 471   /// <param name="pwszVersionRange">The string containing 1 or 2 dotted quad
 472   /// version strings to parse, e.g. [1.0,) that means 1.0.0.0 or newer.</param>
 473   /// <param name="pullMinVersion">A 64-bit unsigned integer representing the
 474   /// minimum version, which may be 0. You can compare this to other
 475   /// versions.</param>
 476   /// <param name="pullMaxVersion">A 64-bit unsigned integer representing the
 477   /// maximum version, which may be MAXULONGLONG. You can compare this to other
 478   /// versions.</param>
 479   /// <returns>Standard HRESULT indicating success or failure.</returns>
 480   STDMETHOD(ParseVersionRange)
 481   (_In_ LPCOLESTR pwszVersionRange, _Out_ PULONGLONG pullMinVersion,
 482    _Out_ PULONGLONG pullMaxVersion) = 0;
 483 };
 484 #endif
 485
 486 // Class declarations
 487 //
 488 EXTERN_C const CLSID CLSID_SetupConfiguration;
 489
 490 #ifdef __cplusplus
 491 /// <summary>
 492 /// This class implements <see cref="ISetupConfiguration"/>, <see
 493 /// cref="ISetupConfiguration2"/>, and <see cref="ISetupHelper"/>.
 494 /// </summary>
 495 class DECLSPEC_UUID("177F0C4A-1CD3-4DE7-A32C-71DBBB9FA36D") SetupConfiguration;
 496 #endif
 497
 498 // Function declarations
 499 //
 500 /// <summary>
 501 /// Gets an <see cref="ISetupConfiguration"/> that provides information about
 502 /// product instances installed on the machine.
 503 /// </summary>
 504 /// <param name="ppConfiguration">The <see cref="ISetupConfiguration"/> that
 505 /// provides information about product instances installed on the
 506 /// machine.</param>
 507 /// <param name="pReserved">Reserved for future use.</param>
 508 /// <returns>Standard HRESULT indicating success or failure.</returns>
 509 STDMETHODIMP GetSetupConfiguration(_Out_ ISetupConfiguration **ppConfiguration,
 510                                    _Reserved_ LPVOID pReserved);
 511
 512 #ifdef __cplusplus
 513 }
 514 #endif