home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Windows Gam…ming Gurus (2nd Edition) / Disc2.iso / vc98 / include / msi.h < prev    next >
C/C++ Source or Header  |  1998-04-25  |  37KB  |  821 lines
  1. /*****************************************************************************\
  2. *                                                                             *
  3. * msi.h - - Interface for external access to Installer Service                *
  4. *                                                                             *
  5. * Version 0.20                                                                *
  6. *                                                                             *
  7. * NOTES:  All buffers sizes are TCHAR count, null included only on input      *
  8. *         Return argument pointers may be null if not interested in value     *
  9. *                                                                             *
  10. * Copyright (c) 1997, Microsoft Corp.      All rights reserved.               *
  11. *                                                                             *
  12. \*****************************************************************************/
  13.  
  14. #ifndef _MSI_H_
  15. #define _MSI_H_
  16.  
  17. // --------------------------------------------------------------------------
  18. // Installer generic handle definitions
  19. // --------------------------------------------------------------------------
  20.  
  21. typedef unsigned long MSIHANDLE;     // abstract generic handle, 0 == no handle
  22.  
  23. #ifdef __cplusplus
  24. extern "C" {
  25. #endif
  26.  
  27. // Close a open handle of any type
  28. // All handles obtained from API calls must be closed when no longer needed
  29. // Normally succeeds, returning TRUE. 
  30.  
  31. UINT WINAPI MsiCloseHandle(MSIHANDLE hAny);
  32.  
  33. // Close all handles open in the process, a diagnostic call
  34. // This should NOT be used as a cleanup mechanism -- use PMSIHANDLE class
  35. // Can be called at termination to assure that all handles have been closed
  36. // Returns 0 if all handles have been close, else number of open handles
  37.  
  38. UINT WINAPI MsiCloseAllHandles();
  39.  
  40. #ifdef __cplusplus
  41. }
  42. #endif
  43.  
  44. #ifdef __cplusplus
  45.  
  46. // C++ wrapper object to automatically free handle when going out of scope
  47.  
  48. class PMSIHANDLE
  49. {
  50.     MSIHANDLE m_h;
  51.  public:
  52.     PMSIHANDLE():m_h(0){}
  53.     PMSIHANDLE(MSIHANDLE h):m_h(h){}
  54.   ~PMSIHANDLE(){if (m_h!=0) MsiCloseHandle(m_h);}
  55.     void operator =(MSIHANDLE h) {if (m_h) MsiCloseHandle(m_h); m_h=h;}
  56.     operator MSIHANDLE() {return m_h;}
  57.     MSIHANDLE* operator &() {if (m_h) MsiCloseHandle(m_h); m_h = 0; return &m_h;}
  58. };
  59. #endif  //__cplusplus
  60.  
  61. // Install message type for callback is a combination of the following:
  62. //  A message box style:      MB_*, where MB_OK is the default
  63. //  A message box icon type:  MB_ICON*, where no icon is the default
  64. //  A default button:         MB_DEFBUTTON?, where MB_DEFBUTTON1 is the default
  65. //  One of the following install message types, no default
  66. typedef enum tagINSTALLMESSAGE
  67. {
  68.     INSTALLMESSAGE_OUTOFMEMORY = 0x00000000L, // out of memory message
  69.     INSTALLMESSAGE_ERROR       = 0x01000000L, // formatted error message
  70.     INSTALLMESSAGE_WARNING     = 0x02000000L, // formatted warning message
  71.     INSTALLMESSAGE_USER        = 0x03000000L, // user request message
  72.     INSTALLMESSAGE_INFO        = 0x04000000L, // informative message for log
  73.     INSTALLMESSAGE_DIAGNOSTIC  = 0x05000000L, // debug notification, display if no log
  74.     INSTALLMESSAGE_COMMONDATA  = 0x06000000L, // product info for dialog: language Id, dialog caption
  75.     INSTALLMESSAGE_RESERVED    = 0x07000000L, // reserved for future use
  76.     INSTALLMESSAGE_ACTIONSTART = 0x08000000L, // start of action: action name & description
  77.     INSTALLMESSAGE_ACTIONDATA  = 0x09000000L, // formatted data associated with individual action item
  78.     INSTALLMESSAGE_PROGRESS    = 0x0A000000L, // progress gauge info: units so far, total
  79.     INSTALLMESSAGE_ACTIONDONE  = 0x0B000000L, // end of action sequence, exit modeless dialog
  80. } INSTALLMESSAGE;
  81.  
  82. // external error handler supplied to installation API functions
  83.  
  84. typedef int (*INSTALLUI_HANDLERA)(LPVOID pvContext, UINT iMessageType, LPCSTR szMessage);
  85. typedef int (*INSTALLUI_HANDLERW)(LPVOID pvContext, UINT iMessageType, LPCWSTR szMessage);
  86. #ifdef UNICODE
  87. #define INSTALLUI_HANDLER  INSTALLUI_HANDLERW
  88. #else
  89. #define INSTALLUI_HANDLER  INSTALLUI_HANDLERA
  90. #endif // !UNICODE
  91.  
  92. typedef enum tagINSTALLUILEVEL
  93. {
  94.     INSTALLUILEVEL_NOCHANGE = 0,   // UI level is unchanged
  95.     INSTALLUILEVEL_DEFAULT  = 1,   // default UI is used
  96.     INSTALLUILEVEL_NONE     = 2,   // completely silent installation
  97.     INSTALLUILEVEL_BASIC    = 3,   // simple progress and error handling
  98.     INSTALLUILEVEL_REDUCED  = 4,   // authored UI, wizard dialogs suppressed
  99.     INSTALLUILEVEL_FULL     = 5,   // authored UI with wizards, progress, errors
  100.     
  101. } INSTALLUILEVEL;
  102.  
  103. typedef enum tagINSTALLSTATE
  104. {
  105.     INSTALLSTATE_BADCONFIG    = -6,  // configuration data corrupt
  106.     INSTALLSTATE_INCOMPLETE   = -5,  // installation suspended or in progress
  107.     INSTALLSTATE_SOURCEABSENT = -4,  // run from source, source is unavailable
  108.     INSTALLSTATE_MOREDATA     = -3,  // return buffer overflow
  109.     INSTALLSTATE_INVALIDARG   = -2,  // invalid function argument
  110.     INSTALLSTATE_UNKNOWN      = -1,  // unrecognized product or feature
  111.     INSTALLSTATE_BROKEN       =  0,  // broken
  112.     INSTALLSTATE_ADVERTISED   =  1,  // advertised
  113.     INSTALLSTATE_ABSENT       =  2,  // uninstalled
  114.     INSTALLSTATE_LOCAL        =  3,  // installed on local drive
  115.     INSTALLSTATE_SOURCE       =  4,  // run from source, CD or net
  116.     INSTALLSTATE_DEFAULT      =  5,  // use default, local or source
  117. } INSTALLSTATE;
  118.  
  119. typedef enum tagUSERINFOSTATE
  120. {
  121.     USERINFOSTATE_MOREDATA   = -3,  // return buffer overflow
  122.     USERINFOSTATE_INVALIDARG = -2,  // invalid function argument
  123.     USERINFOSTATE_UNKNOWN    = -1,  // unrecognized product
  124.     USERINFOSTATE_ABSENT     =  0,  // user info and PID not initialized
  125.     USERINFOSTATE_PRESENT    =  1,  // user info and PID initialized
  126. } USERINFOSTATE;
  127.  
  128. typedef enum tagINSTALLLEVEL
  129. {
  130.     INSTALLLEVEL_DEFAULT = 0,      // install authored default
  131.     INSTALLLEVEL_MINIMUM = 1,      // install only required features
  132.     INSTALLLEVEL_MAXIMUM = 0xFFFF, // install all features
  133. } INSTALLLEVEL;                   // intermediate levels dependent on authoring
  134.  
  135. typedef enum tagREINSTALLMODE  // bit flags
  136. {
  137.     REINSTALLMODE_REPAIR           = 0x00000001,  // repair any defects encountered
  138.     REINSTALLMODE_FILEMISSING      = 0x00000002,  // Reinstall only if file is missing
  139.     REINSTALLMODE_FILEOLDERVERSION = 0x00000004,  // Reinstall if file is missing, or older version
  140.     REINSTALLMODE_FILEEQUALVERSION = 0x00000008,  // Reinstall if file is missing, or equal or older version
  141.     REINSTALLMODE_FILEEXACT        = 0x00000010,  // Reinstall if file is missing, or not exact version
  142.     REINSTALLMODE_FILEVERIFY       = 0x00000020,  // checksum executables, reinstall if missing or corrupt
  143.     REINSTALLMODE_FILEREPLACE      = 0x00000040,  // Reinstall all files, regardless of version
  144.     REINSTALLMODE_MACHINEDATA      = 0x00000080,  // insure required machine reg entries
  145.     REINSTALLMODE_USERDATA         = 0x00000100,  // insure required user reg entries
  146.     REINSTALLMODE_SHORTCUT         = 0x00000200,  // validate shortcuts and progman items
  147. } REINSTALLMODE;
  148.  
  149. typedef enum tagINSTALLOGMODE  // bit flags
  150. {
  151.     INSTALLLOGMODE_OUTOFMEMORY  = (1 << (INSTALLMESSAGE_OUTOFMEMORY >> 24)),
  152.     INSTALLLOGMODE_ERROR        = (1 << (INSTALLMESSAGE_ERROR       >> 24)),
  153.     INSTALLLOGMODE_WARNING      = (1 << (INSTALLMESSAGE_WARNING     >> 24)),
  154.     INSTALLLOGMODE_USER         = (1 << (INSTALLMESSAGE_USER        >> 24)),
  155.     INSTALLLOGMODE_INFO         = (1 << (INSTALLMESSAGE_INFO        >> 24)),
  156.     INSTALLLOGMODE_DIAGNOSTIC   = (1 << (INSTALLMESSAGE_DIAGNOSTIC  >> 24)),
  157.     INSTALLLOGMODE_COMMONDATA   = (1 << (INSTALLMESSAGE_COMMONDATA  >> 24)),
  158.     INSTALLLOGMODE_RESERVED     = (1 << (INSTALLMESSAGE_RESERVED    >> 24)),
  159.     INSTALLLOGMODE_ACTIONSTART  = (1 << (INSTALLMESSAGE_ACTIONSTART >> 24)),
  160.     INSTALLLOGMODE_ACTIONDATA   = (1 << (INSTALLMESSAGE_ACTIONDATA  >> 24)),
  161.     INSTALLLOGMODE_PROPERTYDUMP = (1 << (INSTALLMESSAGE_PROGRESS    >> 24)),
  162. } INSTALLLOGMODE;
  163.  
  164. typedef enum tagINSTALLFEATUREATTRIBUTE // bit flags
  165. {
  166.     INSTALLFEATUREATTRIBUTE_FAVORLOCAL   = 0x00000001,
  167.     INSTALLFEATUREATTRIBUTE_FAVORSOURCE  = 0x00000002,
  168.     INSTALLFEATUREATTRIBUTE_FOLLOWPARENT = 0x00000004,
  169. } INSTALLFEATUREATTRIBUTE;
  170.  
  171.  
  172. typedef enum tagINSTALLSOURCEACTION
  173. {
  174.     INSTALLSOURCEACTION_ADD          =  1,  // add source to list
  175.     INSTALLSOURCEACTION_REMOVE       =  2,  // remove source from list
  176.     INSTALLSOURCEACTION_REMOVEALL    =  3,  // flush entire sourcelist key
  177.     INSTALLSOURCEACTION_REMOVEALLNET =  4,  // flush all network sources
  178.     INSTALLSOURCEACTION_REMOVEALLURL =  5,  // flush all URL sources
  179.     INSTALLSOURCEACTION_ENABLECD     =  6,  // enable searching on CD sources
  180.     INSTALLSOURCEACTION_DISABLECD    =  7,  // disable searching on CD sources
  181. } INSTALLSOURCEACTION;
  182.  
  183.  
  184. #define MAX_FEATURE_CHARS  38   // maximum chars in feature name (same as string GUID)
  185.  
  186.  
  187. // Product info attributes: advertised information
  188.  
  189. #define INSTALLPROPERTY_TRANSFORMS            __TEXT("Transforms")
  190. #define INSTALLPROPERTY_LANGUAGE              __TEXT("Language")
  191. #define INSTALLPROPERTY_PRODUCTNAME           __TEXT("ProductName")
  192.  
  193. // Product info attributes: installed information
  194.  
  195. #define INSTALLPROPERTY_INSTALLEDPRODUCTNAME  __TEXT("InstalledProductName")
  196. #define INSTALLPROPERTY_VERSIONSTRING         __TEXT("VersionString")
  197. #define INSTALLPROPERTY_HELPLINK              __TEXT("HelpLink")
  198. #define INSTALLPROPERTY_HELPTELEPHONE         __TEXT("HelpTelephone")
  199. #define INSTALLPROPERTY_INSTALLLOCATION       __TEXT("InstallLocation")
  200. #define INSTALLPROPERTY_INSTALLSOURCE         __TEXT("InstallSource")
  201. #define INSTALLPROPERTY_INSTALLDATE           __TEXT("InstallDate")
  202. #define INSTALLPROPERTY_PUBLISHER             __TEXT("Publisher")
  203. #define INSTALLPROPERTY_LOCALPACKAGE          __TEXT("LocalPackage")
  204. #define INSTALLPROPERTY_URLINFOABOUT          __TEXT("URLInfoAbout")
  205. #define INSTALLPROPERTY_URLUPDATEINFO         __TEXT("URLUpdateInfo")
  206. #define INSTALLPROPERTY_VERSIONMINOR          __TEXT("VersionMinor")
  207. #define INSTALLPROPERTY_VERSIONMAJOR          __TEXT("VersionMajor")
  208.  
  209.  
  210.  
  211. #ifdef __cplusplus
  212. extern "C" {
  213. #endif
  214.  
  215. // --------------------------------------------------------------------------
  216. // Functions to set the UI handling and logging. The UI will be used for error,
  217. // progress, and log messages for all subsequent calls to Installer Service
  218. // API functions that require UI.
  219. // --------------------------------------------------------------------------
  220.  
  221. // Enable internal UI
  222.  
  223. INSTALLUILEVEL WINAPI MsiSetInternalUI(
  224.     INSTALLUILEVEL  dwUILevel,     // UI level
  225.     HWND  *phWnd);                   // handle of owner window
  226.  
  227. // Enable external UI
  228.  
  229. INSTALLUI_HANDLERA WINAPI MsiSetExternalUIA(
  230.     INSTALLUI_HANDLERA puiHandler,   // for progress and error handling 
  231.     DWORD              dwMessageFilter, // bit flags designating messages to handle
  232.     LPVOID             pvContext);   // application context
  233. INSTALLUI_HANDLERW WINAPI MsiSetExternalUIW(
  234.     INSTALLUI_HANDLERW puiHandler,   // for progress and error handling 
  235.     DWORD              dwMessageFilter, // bit flags designating messages to handle
  236.     LPVOID             pvContext);   // application context
  237. #ifdef UNICODE
  238. #define MsiSetExternalUI  MsiSetExternalUIW
  239. #else
  240. #define MsiSetExternalUI  MsiSetExternalUIA
  241. #endif // !UNICODE
  242.  
  243.  
  244. // Enable logging to a file or extern UI handler for the client process,
  245. // with control over which log messages are passed to the file or handler
  246.  
  247. UINT WINAPI MsiEnableLogA(
  248.     DWORD     dwLogMode,   // bit flags designating operations to report
  249.     LPCSTR  szLogFile,   // log file, or NULL to direct to external handler
  250.     BOOL      fAppend);    // TRUE to append to existing file, FALSE to replace
  251. UINT WINAPI MsiEnableLogW(
  252.     DWORD     dwLogMode,   // bit flags designating operations to report
  253.     LPCWSTR  szLogFile,   // log file, or NULL to direct to external handler
  254.     BOOL      fAppend);    // TRUE to append to existing file, FALSE to replace
  255. #ifdef UNICODE
  256. #define MsiEnableLog  MsiEnableLogW
  257. #else
  258. #define MsiEnableLog  MsiEnableLogA
  259. #endif // !UNICODE
  260.  
  261. // --------------------------------------------------------------------------
  262. // Functions to query and configure a product as a whole.
  263. // A component descriptor string may be used instead of the product code.
  264. // --------------------------------------------------------------------------
  265.  
  266. // Return the installed state for a product
  267.  
  268. INSTALLSTATE WINAPI MsiQueryProductStateA(
  269.     LPCSTR  szProduct);
  270. INSTALLSTATE WINAPI MsiQueryProductStateW(
  271.     LPCWSTR  szProduct);
  272. #ifdef UNICODE
  273. #define MsiQueryProductState  MsiQueryProductStateW
  274. #else
  275. #define MsiQueryProductState  MsiQueryProductStateA
  276. #endif // !UNICODE
  277.  
  278. // Return product info
  279.  
  280. UINT WINAPI MsiGetProductInfoA(
  281.     LPCSTR   szProduct,      // product code, string GUID, or descriptor
  282.     LPCSTR   szAttribute,    // attribute name, case-sensitive
  283.     LPSTR    lpValueBuf,     // returned value, NULL if not desired
  284.     DWORD      *pcchValueBuf); // in/out buffer character count
  285. UINT WINAPI MsiGetProductInfoW(
  286.     LPCWSTR   szProduct,      // product code, string GUID, or descriptor
  287.     LPCWSTR   szAttribute,    // attribute name, case-sensitive
  288.     LPWSTR    lpValueBuf,     // returned value, NULL if not desired
  289.     DWORD      *pcchValueBuf); // in/out buffer character count
  290. #ifdef UNICODE
  291. #define MsiGetProductInfo  MsiGetProductInfoW
  292. #else
  293. #define MsiGetProductInfo  MsiGetProductInfoA
  294. #endif // !UNICODE
  295.  
  296. // Install a new product.
  297. // Either may be NULL, but the DATABASE property must be specfied
  298.  
  299. UINT WINAPI MsiInstallProductA(
  300.     LPCSTR      szPackagePath,    // location of package to install
  301.     LPCSTR      szCommandLine);   // command line <property settings>
  302. UINT WINAPI MsiInstallProductW(
  303.     LPCWSTR      szPackagePath,    // location of package to install
  304.     LPCWSTR      szCommandLine);   // command line <property settings>
  305. #ifdef UNICODE
  306. #define MsiInstallProduct  MsiInstallProductW
  307. #else
  308. #define MsiInstallProduct  MsiInstallProductA
  309. #endif // !UNICODE
  310.  
  311. // Install/uninstall an advertised or installed product
  312. // No action if installed and INSTALLSTATE_DEFAULT specified
  313.  
  314. UINT WINAPI MsiConfigureProductA(
  315.     LPCSTR      szProduct,        // product code OR descriptor
  316.     int          iInstallLevel,    // how much of the product to install
  317.     INSTALLSTATE eInstallState);   // local/source/default/absent/lock/uncache
  318. UINT WINAPI MsiConfigureProductW(
  319.     LPCWSTR      szProduct,        // product code OR descriptor
  320.     int          iInstallLevel,    // how much of the product to install
  321.     INSTALLSTATE eInstallState);   // local/source/default/absent/lock/uncache
  322. #ifdef UNICODE
  323. #define MsiConfigureProduct  MsiConfigureProductW
  324. #else
  325. #define MsiConfigureProduct  MsiConfigureProductA
  326. #endif // !UNICODE
  327.  
  328. // Reinstall product, used to validate or correct problems
  329.  
  330. UINT WINAPI MsiReinstallProductA(
  331.     LPCSTR      szProduct,        // product code OR descriptor
  332.     DWORD         szReinstallMode); // one or more REINSTALLMODE modes
  333. UINT WINAPI MsiReinstallProductW(
  334.     LPCWSTR      szProduct,        // product code OR descriptor
  335.     DWORD         szReinstallMode); // one or more REINSTALLMODE modes
  336. #ifdef UNICODE
  337. #define MsiReinstallProduct  MsiReinstallProductW
  338. #else
  339. #define MsiReinstallProduct  MsiReinstallProductA
  340. #endif // !UNICODE
  341.  
  342. // Return the product code for a registered component, called once by apps
  343.  
  344. UINT WINAPI MsiGetProductCodeA(
  345.     LPCSTR   szComponent,   // component Id registered for this product
  346.     LPSTR    lpBuf39);      // returned string GUID, sized for 39 characters
  347. UINT WINAPI MsiGetProductCodeW(
  348.     LPCWSTR   szComponent,   // component Id registered for this product
  349.     LPWSTR    lpBuf39);      // returned string GUID, sized for 39 characters
  350. #ifdef UNICODE
  351. #define MsiGetProductCode  MsiGetProductCodeW
  352. #else
  353. #define MsiGetProductCode  MsiGetProductCodeA
  354. #endif // !UNICODE
  355.  
  356. // Return the registered user information for an installed product
  357.  
  358. USERINFOSTATE WINAPI MsiGetUserInfoA(
  359.     LPCSTR  szProduct,        // product code, string GUID
  360.     LPSTR   lpUserNameBuf,    // return user name           
  361.     DWORD    *pcchUserNameBuf, // in/out buffer character count
  362.     LPSTR   lpOrgNameBuf,     // return company name           
  363.     DWORD    *pcchOrgNameBuf,  // in/out buffer character count
  364.     LPSTR   lpSerialBuf,      // return product serial number
  365.     DWORD    *pcchSerialBuf);  // in/out buffer character count
  366. USERINFOSTATE WINAPI MsiGetUserInfoW(
  367.     LPCWSTR  szProduct,        // product code, string GUID
  368.     LPWSTR   lpUserNameBuf,    // return user name           
  369.     DWORD    *pcchUserNameBuf, // in/out buffer character count
  370.     LPWSTR   lpOrgNameBuf,     // return company name           
  371.     DWORD    *pcchOrgNameBuf,  // in/out buffer character count
  372.     LPWSTR   lpSerialBuf,      // return product serial number
  373.     DWORD    *pcchSerialBuf);  // in/out buffer character count
  374. #ifdef UNICODE
  375. #define MsiGetUserInfo  MsiGetUserInfoW
  376. #else
  377. #define MsiGetUserInfo  MsiGetUserInfoA
  378. #endif // !UNICODE
  379.  
  380. // Obtain and store user info and PID from installation wizard (first run)
  381.  
  382. UINT WINAPI MsiCollectUserInfoA(
  383.     LPCSTR  szProduct);     // product code, string GUID
  384. UINT WINAPI MsiCollectUserInfoW(
  385.     LPCWSTR  szProduct);     // product code, string GUID
  386. #ifdef UNICODE
  387. #define MsiCollectUserInfo  MsiCollectUserInfoW
  388. #else
  389. #define MsiCollectUserInfo  MsiCollectUserInfoA
  390. #endif // !UNICODE
  391.  
  392. // --------------------------------------------------------------------------
  393. // Functions to query and configure a feature within a product.
  394. // Separate wrapper functions are provided that accept a descriptor string.
  395. // --------------------------------------------------------------------------
  396.  
  397. // Return the installed state for a product feature
  398.  
  399. INSTALLSTATE WINAPI MsiQueryFeatureStateA(
  400.     LPCSTR  szProduct,
  401.     LPCSTR  szFeature);
  402. INSTALLSTATE WINAPI MsiQueryFeatureStateW(
  403.     LPCWSTR  szProduct,
  404.     LPCWSTR  szFeature);
  405. #ifdef UNICODE
  406. #define MsiQueryFeatureState  MsiQueryFeatureStateW
  407. #else
  408. #define MsiQueryFeatureState  MsiQueryFeatureStateA
  409. #endif // !UNICODE
  410.  
  411. // Indicate intent to use a product feature, increments usage count
  412. // Prompts for CD if not loaded, does not install feature
  413.  
  414. INSTALLSTATE WINAPI MsiUseFeatureA(
  415.     LPCSTR  szProduct,
  416.     LPCSTR  szFeature);
  417. INSTALLSTATE WINAPI MsiUseFeatureW(
  418.     LPCWSTR  szProduct,
  419.     LPCWSTR  szFeature);
  420. #ifdef UNICODE
  421. #define MsiUseFeature  MsiUseFeatureW
  422. #else
  423. #define MsiUseFeature  MsiUseFeatureA
  424. #endif // !UNICODE
  425.  
  426. // Return the usage metrics for a product feature
  427.  
  428. UINT WINAPI MsiGetFeatureUsageA(
  429.     LPCSTR      szProduct,        // product code
  430.     LPCSTR      szFeature,        // feature ID
  431.     DWORD        *pdwUseCount,     // returned use count
  432.     WORD         *pwDateUsed);     // last date used (DOS date format)
  433. UINT WINAPI MsiGetFeatureUsageW(
  434.     LPCWSTR      szProduct,        // product code
  435.     LPCWSTR      szFeature,        // feature ID
  436.     DWORD        *pdwUseCount,     // returned use count
  437.     WORD         *pwDateUsed);     // last date used (DOS date format)
  438. #ifdef UNICODE
  439. #define MsiGetFeatureUsage  MsiGetFeatureUsageW
  440. #else
  441. #define MsiGetFeatureUsage  MsiGetFeatureUsageA
  442. #endif // !UNICODE
  443.  
  444. // Force the installed state for a product feature
  445.  
  446. UINT WINAPI MsiConfigureFeatureA(
  447.     LPCSTR  szProduct,
  448.     LPCSTR  szFeature,
  449.     INSTALLSTATE eInstallState);   // local/source/default/absent/lock/uncache
  450. UINT WINAPI MsiConfigureFeatureW(
  451.     LPCWSTR  szProduct,
  452.     LPCWSTR  szFeature,
  453.     INSTALLSTATE eInstallState);   // local/source/default/absent/lock/uncache
  454. #ifdef UNICODE
  455. #define MsiConfigureFeature  MsiConfigureFeatureW
  456. #else
  457. #define MsiConfigureFeature  MsiConfigureFeatureA
  458. #endif // !UNICODE
  459.  
  460.  
  461. // Reinstall feature, used to validate or correct problems
  462.  
  463. UINT WINAPI MsiReinstallFeatureA(
  464.     LPCSTR      szProduct,        // product code
  465.     LPCSTR      szFeature,        // feature ID, NULL for entire product
  466.     DWORD         dwReinstallMode); // one or more REINSTALLMODE modes
  467. UINT WINAPI MsiReinstallFeatureW(
  468.     LPCWSTR      szProduct,        // product code
  469.     LPCWSTR      szFeature,        // feature ID, NULL for entire product
  470.     DWORD         dwReinstallMode); // one or more REINSTALLMODE modes
  471. #ifdef UNICODE
  472. #define MsiReinstallFeature  MsiReinstallFeatureW
  473. #else
  474. #define MsiReinstallFeature  MsiReinstallFeatureA
  475. #endif // !UNICODE
  476.  
  477. // --------------------------------------------------------------------------
  478. // Functions to return a path to a particular component.
  479. // The state of the feature being used should have been checked previously.
  480. // --------------------------------------------------------------------------
  481.  
  482. // Return full path to an installed component
  483.  
  484. INSTALLSTATE WINAPI MsiLocateComponentA(
  485.     LPCSTR szComponent,  // component Id, string GUID
  486.     LPSTR  lpPathBuf,    // returned path
  487.     DWORD   *pcchBuf);    // in/out buffer character count
  488. INSTALLSTATE WINAPI MsiLocateComponentW(
  489.     LPCWSTR szComponent,  // component Id, string GUID
  490.     LPWSTR  lpPathBuf,    // returned path
  491.     DWORD   *pcchBuf);    // in/out buffer character count
  492. #ifdef UNICODE
  493. #define MsiLocateComponent  MsiLocateComponentW
  494. #else
  495. #define MsiLocateComponent  MsiLocateComponentA
  496. #endif // !UNICODE
  497.  
  498. // Return full component path, performing any necessary installation
  499. // calls MsiQueryFeatureState to detect that all components are installed
  500. // then calls MsiConfigureFeature if any of its components are uninstalled
  501. // then calls MsiLocateComponent to obtain the path the its key file
  502.  
  503. UINT WINAPI MsiProvideComponentA(
  504.     LPCSTR     szProduct,    // product code in case install required
  505.     LPCSTR     szFeature,    // feature ID in case install required
  506.     LPCSTR     szComponent,  // component ID
  507.     DWORD        dwReserved,   // reserved, must be 0
  508.     LPSTR      lpPathBuf,    // returned path, NULL if not desired
  509.     DWORD       *pcchPathBuf);// in/out buffer character count
  510. UINT WINAPI MsiProvideComponentW(
  511.     LPCWSTR     szProduct,    // product code in case install required
  512.     LPCWSTR     szFeature,    // feature ID in case install required
  513.     LPCWSTR     szComponent,  // component ID
  514.     DWORD        dwReserved,   // reserved, must be 0
  515.     LPWSTR      lpPathBuf,    // returned path, NULL if not desired
  516.     DWORD       *pcchPathBuf);// in/out buffer character count
  517. #ifdef UNICODE
  518. #define MsiProvideComponent  MsiProvideComponentW
  519. #else
  520. #define MsiProvideComponent  MsiProvideComponentA
  521. #endif // !UNICODE
  522.  
  523. // For an advertised component that registers descriptor strings,
  524. // return full component path, performing any necessary installation.
  525. // If the qualifier is NULL the default component, if present, will 
  526. // be provided. Calls MsiProvideComponentFromDescriptor to install
  527. // and return the path.
  528.  
  529. UINT WINAPI MsiProvideQualifiedComponentA(
  530.     LPCSTR     szCategory,   // component category ID
  531.     LPCSTR     szQualifier,  // specifies which component to access
  532.     DWORD        dwReserved,   // reserved, must be 0
  533.     LPSTR      lpPathBuf,    // returned path, NULL if not desired
  534.     DWORD       *pcchPathBuf); // in/out buffer character count
  535. UINT WINAPI MsiProvideQualifiedComponentW(
  536.     LPCWSTR     szCategory,   // component category ID
  537.     LPCWSTR     szQualifier,  // specifies which component to access
  538.     DWORD        dwReserved,   // reserved, must be 0
  539.     LPWSTR      lpPathBuf,    // returned path, NULL if not desired
  540.     DWORD       *pcchPathBuf); // in/out buffer character count
  541. #ifdef UNICODE
  542. #define MsiProvideQualifiedComponent  MsiProvideQualifiedComponentW
  543. #else
  544. #define MsiProvideQualifiedComponent  MsiProvideQualifiedComponentA
  545. #endif // !UNICODE
  546.  
  547. // --------------------------------------------------------------------------
  548. // Functions to iterate registered products, features, and components.
  549. // As with reg keys, they accept a 0-based index into the enumeration.
  550. // --------------------------------------------------------------------------
  551.  
  552. // Enumerate the registered products, either installed or advertised
  553.  
  554. UINT WINAPI MsiEnumProductsA(
  555.     DWORD     iProductIndex,    // 0-based index into registered products
  556.     LPSTR   lpProductBuf);    // buffer of char count: 39 (size of string GUID)
  557. UINT WINAPI MsiEnumProductsW(
  558.     DWORD     iProductIndex,    // 0-based index into registered products
  559.     LPWSTR   lpProductBuf);    // buffer of char count: 39 (size of string GUID)
  560. #ifdef UNICODE
  561. #define MsiEnumProducts  MsiEnumProductsW
  562. #else
  563. #define MsiEnumProducts  MsiEnumProductsA
  564. #endif // !UNICODE
  565.  
  566. // Enumerate the advertised features for a given product.
  567. // If parent is not required, supplying NULL will improve performance.
  568.  
  569. UINT WINAPI MsiEnumFeaturesA(
  570.     LPCSTR  szProduct,
  571.     DWORD     iFeatureIndex,  // 0-based index into published features
  572.     LPSTR   lpFeatureBuf,   // feature name buffer,   size=MAX_FEATURE_CHARS+1
  573.     LPSTR   lpParentBuf);   // parent feature buffer, size=MAX_FEATURE_CHARS+1
  574. UINT WINAPI MsiEnumFeaturesW(
  575.     LPCWSTR  szProduct,
  576.     DWORD     iFeatureIndex,  // 0-based index into published features
  577.     LPWSTR   lpFeatureBuf,   // feature name buffer,   size=MAX_FEATURE_CHARS+1
  578.     LPWSTR   lpParentBuf);   // parent feature buffer, size=MAX_FEATURE_CHARS+1
  579. #ifdef UNICODE
  580. #define MsiEnumFeatures  MsiEnumFeaturesW
  581. #else
  582. #define MsiEnumFeatures  MsiEnumFeaturesA
  583. #endif // !UNICODE
  584.  
  585. // Enumerate the installed components for all products
  586.  
  587. UINT WINAPI MsiEnumComponentsA(
  588.     DWORD    iComponentIndex,  // 0-based index into installed components
  589.     LPSTR   lpComponentBuf);  // buffer of char count: 39 (size of string GUID)
  590. UINT WINAPI MsiEnumComponentsW(
  591.     DWORD    iComponentIndex,  // 0-based index into installed components
  592.     LPWSTR   lpComponentBuf);  // buffer of char count: 39 (size of string GUID)
  593. #ifdef UNICODE
  594. #define MsiEnumComponents  MsiEnumComponentsW
  595. #else
  596. #define MsiEnumComponents  MsiEnumComponentsA
  597. #endif // !UNICODE
  598.  
  599. // Enumerate the client products for a component
  600.  
  601. UINT WINAPI MsiEnumClientsA(
  602.     LPCSTR  szComponent,
  603.     DWORD     iProductIndex,    // 0-based index into client products
  604.     LPSTR   lpProductBuf);    // buffer of char count: 39 (size of string GUID)
  605. UINT WINAPI MsiEnumClientsW(
  606.     LPCWSTR  szComponent,
  607.     DWORD     iProductIndex,    // 0-based index into client products
  608.     LPWSTR   lpProductBuf);    // buffer of char count: 39 (size of string GUID)
  609. #ifdef UNICODE
  610. #define MsiEnumClients  MsiEnumClientsW
  611. #else
  612. #define MsiEnumClients  MsiEnumClientsA
  613. #endif // !UNICODE
  614.  
  615. // Enumerate the qualifiers for an advertised component.
  616.  
  617. UINT WINAPI MsiEnumComponentQualifiersA(
  618.     LPCSTR   szComponent,         // generic component ID that is qualified
  619.     DWORD     iIndex,               // 0-based index into qualifiers
  620.     LPSTR    lpQualifierBuf,      // qualifier buffer
  621.     DWORD     *pcchQualifierBuf,   // in/out qualifier buffer character count
  622.     LPSTR    lpDescriptionBuf,    // description buffer
  623.     DWORD     *pcchDescriptionBuf); // in/out description buffer character count
  624. UINT WINAPI MsiEnumComponentQualifiersW(
  625.     LPCWSTR   szComponent,         // generic component ID that is qualified
  626.     DWORD     iIndex,               // 0-based index into qualifiers
  627.     LPWSTR    lpQualifierBuf,      // qualifier buffer
  628.     DWORD     *pcchQualifierBuf,   // in/out qualifier buffer character count
  629.     LPWSTR    lpDescriptionBuf,    // description buffer
  630.     DWORD     *pcchDescriptionBuf); // in/out description buffer character count
  631. #ifdef UNICODE
  632. #define MsiEnumComponentQualifiers  MsiEnumComponentQualifiersW
  633. #else
  634. #define MsiEnumComponentQualifiers  MsiEnumComponentQualifiersA
  635. #endif // !UNICODE
  636.  
  637. // --------------------------------------------------------------------------
  638. // Functions to obtain product or package information.
  639. // --------------------------------------------------------------------------
  640.  
  641. // Open the installation for a product to obtain detailed information
  642.  
  643. UINT WINAPI MsiOpenProductA(
  644.     LPCSTR   szProduct,    // product code OR descriptor
  645.     MSIHANDLE  *hProduct);   // returned product handle, must be closed
  646. UINT WINAPI MsiOpenProductW(
  647.     LPCWSTR   szProduct,    // product code OR descriptor
  648.     MSIHANDLE  *hProduct);   // returned product handle, must be closed
  649. #ifdef UNICODE
  650. #define MsiOpenProduct  MsiOpenProductW
  651. #else
  652. #define MsiOpenProduct  MsiOpenProductA
  653. #endif // !UNICODE
  654.  
  655. // Open a product package in order to access product properties
  656.  
  657. UINT WINAPI MsiOpenPackageA(
  658.     LPCSTR    szPackagePath,     // location of package
  659.     MSIHANDLE  *hProduct);         // returned product handle, must be closed
  660. UINT WINAPI MsiOpenPackageW(
  661.     LPCWSTR    szPackagePath,     // location of package
  662.     MSIHANDLE  *hProduct);         // returned product handle, must be closed
  663. #ifdef UNICODE
  664. #define MsiOpenPackage  MsiOpenPackageW
  665. #else
  666. #define MsiOpenPackage  MsiOpenPackageA
  667. #endif // !UNICODE
  668.  
  669. // Provide the value for an installation property.
  670.  
  671. UINT WINAPI MsiGetProductPropertyA(
  672.     MSIHANDLE   hProduct,       // product handle obtained from MsiOpenProduct
  673.     LPCSTR    szProperty,     // property name, case-sensitive
  674.     LPSTR     lpValueBuf,     // returned value, NULL if not desired
  675.     DWORD      *pcchValueBuf); // in/out buffer character count
  676. UINT WINAPI MsiGetProductPropertyW(
  677.     MSIHANDLE   hProduct,       // product handle obtained from MsiOpenProduct
  678.     LPCWSTR    szProperty,     // property name, case-sensitive
  679.     LPWSTR     lpValueBuf,     // returned value, NULL if not desired
  680.     DWORD      *pcchValueBuf); // in/out buffer character count
  681. #ifdef UNICODE
  682. #define MsiGetProductProperty  MsiGetProductPropertyW
  683. #else
  684. #define MsiGetProductProperty  MsiGetProductPropertyA
  685. #endif // !UNICODE
  686.  
  687.  
  688. // Determine whether a file is a package
  689. // Returns ERROR_SUCCESS if file is a package.
  690.  
  691. UINT WINAPI MsiVerifyPackageA(
  692.     LPCSTR      szPackagePath);   // location of package
  693. UINT WINAPI MsiVerifyPackageW(
  694.     LPCWSTR      szPackagePath);   // location of package
  695. #ifdef UNICODE
  696. #define MsiVerifyPackage  MsiVerifyPackageW
  697. #else
  698. #define MsiVerifyPackage  MsiVerifyPackageA
  699. #endif // !UNICODE
  700.  
  701.  
  702. // Provide descriptive information for product feature: title and description.
  703. // Returns the install level for the feature, or -1 if feature is unknown.
  704. //   0 = feature is not available on this machine
  705. //   1 = highest priority, feature installed if parent is installed
  706. //  >1 = decreasing priority, feature installation based on InstallLevel property
  707.  
  708. UINT WINAPI MsiGetFeatureInfoA(
  709.     MSIHANDLE   hProduct,       // product handle obtained from MsiOpenProduct
  710.     LPCSTR    szFeature,      // feature name
  711.     DWORD      *lpAttributes,  // attribute flags for the feature <to be defined>
  712.     LPSTR     lpTitleBuf,     // returned localized name, NULL if not desired
  713.     DWORD      *pcchTitleBuf,  // in/out buffer character count
  714.     LPSTR     lpHelpBuf,      // returned description, NULL if not desired
  715.     DWORD      *pcchHelpBuf);  // in/out buffer character count
  716. UINT WINAPI MsiGetFeatureInfoW(
  717.     MSIHANDLE   hProduct,       // product handle obtained from MsiOpenProduct
  718.     LPCWSTR    szFeature,      // feature name
  719.     DWORD      *lpAttributes,  // attribute flags for the feature <to be defined>
  720.     LPWSTR     lpTitleBuf,     // returned localized name, NULL if not desired
  721.     DWORD      *pcchTitleBuf,  // in/out buffer character count
  722.     LPWSTR     lpHelpBuf,      // returned description, NULL if not desired
  723.     DWORD      *pcchHelpBuf);  // in/out buffer character count
  724. #ifdef UNICODE
  725. #define MsiGetFeatureInfo  MsiGetFeatureInfoW
  726. #else
  727. #define MsiGetFeatureInfo  MsiGetFeatureInfoA
  728. #endif // !UNICODE
  729.  
  730. // --------------------------------------------------------------------------
  731. // Functions to install missing components and files. These should be used
  732. // as a last resort.
  733. // --------------------------------------------------------------------------
  734.  
  735. // Install a component unexpectedly missing, provided only for error recovery
  736. // This would typically occur due to failue to establish feature availability
  737. // The product feature having the smallest incremental cost is installed
  738.  
  739. UINT WINAPI MsiInstallMissingComponentA(
  740.     LPCSTR      szProduct,        // product code
  741.     LPCSTR      szComponent,      // component Id, string GUID
  742.     INSTALLSTATE eInstallState);  // local/source/default, absent invalid
  743. UINT WINAPI MsiInstallMissingComponentW(
  744.     LPCWSTR      szProduct,        // product code
  745.     LPCWSTR      szComponent,      // component Id, string GUID
  746.     INSTALLSTATE eInstallState);  // local/source/default, absent invalid
  747. #ifdef UNICODE
  748. #define MsiInstallMissingComponent  MsiInstallMissingComponentW
  749. #else
  750. #define MsiInstallMissingComponent  MsiInstallMissingComponentA
  751. #endif // !UNICODE
  752.  
  753. // Install a file unexpectedly missing, provided only for error recovery
  754. // This would typically occur due to failue to establish feature availability
  755. // The missing component is determined from the product's File table, then
  756. // the product feature having the smallest incremental cost is installed
  757.  
  758. UINT WINAPI MsiInstallMissingFileA(
  759.     LPCSTR      szProduct,        // product code
  760.     LPCSTR      szFile);          // file name, without path
  761. UINT WINAPI MsiInstallMissingFileW(
  762.     LPCWSTR      szProduct,        // product code
  763.     LPCWSTR      szFile);          // file name, without path
  764. #ifdef UNICODE
  765. #define MsiInstallMissingFile  MsiInstallMissingFileW
  766. #else
  767. #define MsiInstallMissingFile  MsiInstallMissingFileA
  768. #endif // !UNICODE
  769.  
  770. #ifdef __cplusplus
  771. }
  772. #endif
  773.  
  774. // --------------------------------------------------------------------------
  775. // Error codes for installer access functions - until merged to winerr.h
  776. // --------------------------------------------------------------------------
  777.  
  778. #ifndef ERROR_INSTALL_FAILURE
  779. #define ERROR_INSTALL_USEREXIT      1602L  // User cancel installation.
  780. #define ERROR_INSTALL_FAILURE       1603L  // Fatal error during installation.
  781. #define ERROR_INSTALL_SUSPEND       1604L  // Installation suspended, incomplete.
  782. #define ERROR_UNKNOWN_PRODUCT       1605L  // Product code not registered.
  783. #define ERROR_UNKNOWN_FEATURE       1606L  // Feature ID not registered.
  784. #define ERROR_UNKNOWN_COMPONENT     1607L  // Component ID not registered.
  785. #define ERROR_UNKNOWN_PROPERTY      1608L  // Unknown property.
  786. #define ERROR_INVALID_HANDLE_STATE  1609L  // Handle is in an invalid state.
  787. #define ERROR_BAD_CONFIGURATION     1610L  // Configuration data corrupt.
  788. #define ERROR_INDEX_ABSENT          1611L  // Component qualifier not present.
  789. #define ERROR_INSTALL_SOURCE_ABSENT 1612L  // Install source unavailable.
  790. #define ERROR_PRODUCT_UNINSTALLED   1614L  // Product is uninstalled.
  791. #define ERROR_BAD_QUERY_SYNTAX      1615L  // SQL query syntax invalid or unsupported.
  792. #define ERROR_INVALID_FIELD         1616L  // Record field does not exist.
  793. #endif
  794.  
  795. #ifndef ERROR_INSTALL_STARTING
  796. #define ERROR_INSTALL_STARTING             1600L // Preparing to install...
  797. #define ERROR_INSTALL_SERVICE_FAILURE      1601L // Failure accessing installation service.
  798. #define ERROR_INSTALL_PACKAGE_VERSION      1613L // Database version unsupported.
  799. #define ERROR_INVALID_COMMAND_LINE         1617L // Invalid command line argument.
  800. #define ERROR_INSTALL_ALREADY_RUNNING      1618L // An installation is in progress.
  801. #define ERROR_INSTALL_PACKAGE_OPEN_FAILED  1619L // Installation package could not be opened.
  802. #define ERROR_INSTALL_PACKAGE_INVALID      1620L // Installation package invalid.
  803. #define ERROR_INSTALL_UI_FAILURE           1621L // Could not initialize installer user interface.
  804. #define ERROR_INSTALL_LOG_FAILURE          1622L // Error opening installation log file.
  805. #define ERROR_INSTALL_LANGUAGE_UNSUPPORTED 1623L // Product language not supported by system.
  806. #define ERROR_INSTALL_TRANFORM_FAILURE     1624L // Error applying transform to install package.
  807. #define ERROR_INSTALL_PACKAGE_REJECTED     1625L // Install package signature not accepted.
  808. #define ERROR_FUNCTION_NOT_CALLED          1626L // Function could not be executed.
  809. #define ERROR_FUNCTION_FAILED              1627L // Function failed during execution.
  810. #define ERROR_INVALID_TABLE                1628L // Invalid or unknown table specified.
  811. #define ERROR_DATATYPE_MISMATCH            1629L // Data supplied is of wrong type.
  812. #define ERROR_UNSUPPORTED_TYPE             1630L // Data of this type is not supported.
  813. #define ERROR_CREATE_FAILED                1631L // Data of this type is not supported.
  814. #endif
  815.  
  816. #ifndef ERROR_INSTALL_TEMP_UNWRITABLE      
  817. #define ERROR_INSTALL_TEMP_UNWRITABLE      1632L // Temp folder is full or inaccessible
  818. #endif
  819.  
  820. #endif // _MSI_H_
  821.