msiquery.h

vc6.0完整版

/*****************************************************************************\
*                                                                             *
* MsiQuery.h - Interface to running installer for custom actions and tools    *
*                                                                             *
* Version 0.20                                                                *
*                                                                             *
* NOTES:  All buffers sizes are TCHAR count, null included only on input      *
*         Return argument pointers may be null if not interested in value     *
*         Returned handles of all types must be closed: MsiCloseHandle(h)     *
*         Functions with UINT return type return a system error code          *
*                                                                             *
* Copyright (c) 1997, Microsoft Corp.      All rights reserved.               *
*                                                                             *
\*****************************************************************************/

#ifndef _MSIQUERY_H_
#define _MSIQUERY_H_
#include "msi.h"  // INSTALLSTATE


#define MSI_NULL_INTEGER 0x80000000  // integer value reserved for null

// MsiOpenDatabase persist predefine values, otherwise output database path is used
#define MSIDBOPEN_READONLY  (LPCTSTR)0  // database open read-only, no persistent changes
#define MSIDBOPEN_TRANSACT  (LPCTSTR)1  // database read/write in transaction mode
#define MSIDBOPEN_DIRECT    (LPCTSTR)2  // database direct read/write without transaction
#define MSIDBOPEN_CREATE    (LPCTSTR)3  // create new database, direct mode read/write

typedef enum tagMSIDBSTATE
{
	MSIDBSTATE_ERROR    =-1,  // invalid database handle
	MSIDBSTATE_READ     = 0,  // database open read-only, no persistent changes
	MSIDBSTATE_WRITE    = 1,  // database readable and updatable
} MSIDBSTATE;

typedef enum tagMSIMODIFY
{
	MSIMODIFY_REFRESH          = 0,  // refetch current record data
	MSIMODIFY_INSERT           = 1,  // insert new record, fails if matching key exists
	MSIMODIFY_UPDATE           = 2,  // update existing non-key data of fetched record
	MSIMODIFY_ASSIGN           = 3,  // insert record, replacing any existing record
	MSIMODIFY_REPLACE          = 4,  // update record, delete old if primary key edit
	MSIMODIFY_MERGE            = 5,  // fails if record with duplicate key not identical
	MSIMODIFY_DELETE           = 6,  // remove row referenced by this record from table
	MSIMODIFY_INSERT_TEMPORARY = 7,  // insert a temporary record
	MSIMODIFY_VALIDATE         = 8,  // validate a fetched record
	MSIMODIFY_VALIDATE_NEW     = 9,  // validate a new record
	MSIMODIFY_VALIDATE_FIELD   = 10, // validate field(s) of an incomplete record
	MSIMODIFY_VALIDATE_DELETE  = 11, // validate before deleting record
} MSIMODIFY;

typedef enum tagMSICOLINFO
{
	MSICOLINFO_NAMES = 0,  // return column names
	MSICOLINFO_TYPES = 1,  // return column definitions, datatype code followed by width
} MSICOLINFO;

typedef enum tagMSICONDITION
{
	MSICONDITION_FALSE = 0,  // expression evaluates to False
	MSICONDITION_TRUE  = 1,  // expression evaluates to True
	MSICONDITION_NONE  = 2,  // no expression present
	MSICONDITION_ERROR = 3,  // syntax error in expression
} MSICONDITION;

typedef enum tagMSIMESSAGE
{
	MSIMESSAGE_OutOfMemory =  0x00000000L, // out of memory, may call recursively
	MSIMESSAGE_Error       =  0x01000000L, // error message,   [1] is message number in Error table
	MSIMESSAGE_Warning     =  0x02000000L, // warning message, [1] message number in Error table
	MSIMESSAGE_User        =  0x03000000L, // user request,    [1] message number in Error table
	MSIMESSAGE_Info        =  0x04000000L, // informative message for log, not to be displayed
	MSIMESSAGE_Diagnostic  =  0x05000000L, // debug notification, displayed only if no log
	MSIMESSAGE_CommonData  =  0x06000000L, // info for UI: [1]=language Id, [2]=dialog caption
	MSIMESSAGE_Reserved    =  0x07000000L, // reserved for future use
	MSIMESSAGE_ActionStart =  0x08000000L, // progress: start of action, [1] action name, [2] description
	MSIMESSAGE_ActionData  =  0x09000000L, // progress: data associated with individual action item
	MSIMESSAGE_Progress    =  0x0A000000L, // progress: gauge info, [1] units so far, [2] total
	MSIMESSAGE_ActionDone  =  0x0B000000L, // progress: end of action sequence, exit modeless dialog
} MSIMESSAGE;

typedef enum tagMSICOSTTREE
{
	MSICOSTTREE_SELFONLY = 0,
	MSICOSTTREE_CHILDREN = 1,
	MSICOSTTREE_PARENTS  = 2,
	MSICOSTTREE_PRODUCT  = 3,
} MSICOSTTREE;

typedef enum tagMSIDBERROR
{
	MSIDBERROR_INVALIDARG        = -3, //  invalid argument
	MSIDBERROR_MOREDATA          = -2, //  buffer too small
	MSIDBERROR_FUNCTIONERROR     = -1, //  function error
	MSIDBERROR_NOERROR           = 0,  //  no error
	MSIDBERROR_DUPLICATEKEY      = 1,  //  new record duplicates primary keys of existing record in table
	MSIDBERROR_REQUIRED          = 2,  //  non-nullable column, no null values allowed
	MSIDBERROR_BADLINK           = 3,  //  corresponding record in foreign table not found
	MSIDBERROR_OVERFLOW          = 4,  //  data greater than maximum value allowed
	MSIDBERROR_UNDERFLOW         = 5,  //  data less than minimum value allowed
	MSIDBERROR_NOTINSET          = 6,  //  data not a member of the values permitted in the set
	MSIDBERROR_BADVERSION        = 7,  //  invalid version string
	MSIDBERROR_BADCASE           = 8,  //  invalid case, must be all upper-case or all lower-case
	MSIDBERROR_BADGUID           = 9,  //  invalid GUID
	MSIDBERROR_BADWILDCARD       = 10, //  invalid wildcardfilename or use of wildcards
	MSIDBERROR_BADIDENTIFIER     = 11, //  bad identifier
	MSIDBERROR_BADLANGUAGE       = 12, //  bad language Id(s)
	MSIDBERROR_BADFILENAME       = 13, //  bad filename
	MSIDBERROR_BADPATH           = 14, //  bad path
	MSIDBERROR_BADCONDITION      = 15, //  bad conditional statement
	MSIDBERROR_BADFORMATTED      = 16, //  bad format string
	MSIDBERROR_BADTEMPLATE       = 17, //  bad template string
	MSIDBERROR_BADDEFAULTDIR     = 18, //  bad string in DefaultDir column of Directory table
	MSIDBERROR_BADREGPATH        = 19, //  bad registry path string
	MSIDBERROR_BADCUSTOMSOURCE   = 20, //  bad string in CustomSource column of CustomAction table
	MSIDBERROR_BADPROPERTY       = 21, //  bad property string
	MSIDBERROR_MISSINGDATA       = 22, //  _Validation table missing reference to column
	MSIDBERROR_BADCATEGORY       = 23, //  Category column of _Validation table for column is invalid
	MSIDBERROR_BADKEYTABLE       = 24, //  table in KeyTable column of _Validation table could not be found/loaded
	MSIDBERROR_BADMAXMINVALUES   = 25, //  value in MaxValue column of _Validation table is less than value in MinValue column
	MSIDBERROR_BADCABINET        = 26, //  bad cabinet name
	MSIDBERROR_BADSHORTCUT       = 27, //  bad shortcut target
	MSIDBERROR_STRINGOVERFLOW    = 28, //  string overflow (greater than length allowed in column def)
	MSIDBERROR_BADLOCALIZEATTRIB = 29  //  invalid localization attribute (primary keys cannot be localized)

} MSIDBERROR;

typedef enum tagMSIRUNMODE
{
	MSIRUNMODE_ADMIN           =  0, // admin mode install, else product install
	MSIRUNMODE_ADVERTISE       =  1, // installing advertisements, else installing or updating product
	MSIRUNMODE_MAINTENANCE     =  2, // modifying an existing installation, else new installation
	MSIRUNMODE_ROLLBACKENABLED =  3, // rollback is enabled
	MSIRUNMODE_LOGENABLED      =  4, // log file active, enabled prior to install session
	MSIRUNMODE_OPERATIONS      =  5, // spooling execute operations, else in determination phase
	MSIRUNMODE_REBOOTATEND     =  6, // reboot needed after successful installation (settable)
	MSIRUNMODE_REBOOTNOW       =  7, // reboot needed to continue installation (settable)
	MSIRUNMODE_CABINET         =  8, // installing files from cabinets and files using Media table
	MSIRUNMODE_SOURCESHORTNAMES=  9, // source LongFileNames suppressed via PID_MSISOURCE summary property
	MSIRUNMODE_TARGETSHORTNAMES= 10, // target LongFileNames suppressed via SHORTFILENAMES property
	MSIRUNMODE_RESERVED11      = 11, // future use
	MSIRUNMODE_WINDOWS9X       = 12, // operating systems is Windows9?, else Windows NT
	MSIRUNMODE_ZAWENABLED      = 13, // operating system supports demand installation
	MSIRUNMODE_RESERVED14      = 14, // future use
	MSIRUNMODE_RESERVED15      = 15, // future use
} MSIRUNMODE;

#define MSIMESSAGE_TYPEMASK = 0xFF000000L  // mask for type code

// Note: MSIMESSAGE_ERROR, MSIMESSAGE_WARNING, MSIMESSAGE_USER are to or'd
// with a message box style to indicate the buttons to display and return:
// MB_OK,MB_OKCANCEL,MB_ABORTRETRYIGNORE,MB_YESNOCANCEL,MB_YESNO,MB_RETRYCANCEL
// the default button (MB_DEFBUTTON1 is normal default):
// MB_DEFBUTTON1, MB_DEFBUTTON2, MB_DEFBUTTON3
// and optionally an icon style:
// MB_ICONERROR, MB_ICONQUESTION, MB_ICONWARNING, MB_ICONINFORMATION

#ifdef __cplusplus
extern "C" {
#endif

// --------------------------------------------------------------------------
// Installer database access functions
// --------------------------------------------------------------------------

// Prepare a database query, creating a view object
// Returns ERROR_SUCCESS if successful, and the view handle is returned,
// else ERROR_INVALID_HANDLE, ERROR_INVALID_HANDLE_STATE, ERROR_BAD_QUERY_SYNTAX, ERROR_GEN_FAILURE

UINT WINAPI MsiDatabaseOpenViewA(MSIHANDLE hDatabase,
	LPCSTR     szQuery,            // SQL query to be prepared
	MSIHANDLE*  phView);            // returned view if TRUE
UINT WINAPI MsiDatabaseOpenViewW(MSIHANDLE hDatabase,
	LPCWSTR     szQuery,            // SQL query to be prepared
	MSIHANDLE*  phView);            // returned view if TRUE
#ifdef UNICODE
#define MsiDatabaseOpenView  MsiDatabaseOpenViewW
#else
#define MsiDatabaseOpenView  MsiDatabaseOpenViewA
#endif // !UNICODE

// Returns the MSIDBERROR enum and name of the column corresponding to the error
// Similar to a GetLastError function, but for the view.  
// Returns errors of MsiViewModify.

MSIDBERROR WINAPI MsiViewGetErrorA(MSIHANDLE hView,
	LPSTR szColumnNameBuffer,  // buffer to hold column name 
	DWORD* pcchBuf);			 // size of buffer
MSIDBERROR WINAPI MsiViewGetErrorW(MSIHANDLE hView,
	LPWSTR szColumnNameBuffer,  // buffer to hold column name 
	DWORD* pcchBuf);			 // size of buffer
#ifdef UNICODE
#define MsiViewGetError  MsiViewGetErrorW
#else
#define MsiViewGetError  MsiViewGetErrorA
#endif // !UNICODE

// Exectute the view query, supplying parameters as required
// Returns ERROR_SUCCESS, ERROR_INVALID_HANDLE, ERROR_INVALID_HANDLE_STATE, ERROR_GEN_FAILURE

UINT WINAPI MsiViewExecute(MSIHANDLE hView,
	MSIHANDLE hRecord);             // optional parameter record, or 0 if none

// Fetch the next sequential record from the view
// Result is ERROR_SUCCESS if a row is found, and its handle is returned
// else ERROR_NO_DATA if no records remain, and a null handle is returned
// else result is error: ERROR_INVALID_HANDLE_STATE, ERROR_INVALID_HANDLE, ERROR_GEN_FAILURE

UINT WINAPI MsiViewFetch(MSIHANDLE hView,
	MSIHANDLE  *phRecord);          // returned data record if fetch succeeds

// Modify a database record, parameters must match types in query columns
// Returns ERROR_SUCCESS, ERROR_INVALID_HANDLE, ERROR_INVALID_HANDLE_STATE, ERROR_GEN_FAILURE, ERROR_ACCESS_DENIED

UINT WINAPI MsiViewModify(MSIHANDLE hView,
	MSIMODIFY eModifyMode,         // modify action to perform
	MSIHANDLE hRecord);            // record obtained from fetch, or new record

// Return the column names or specifications for the current view
// Returns ERROR_SUCCESS, ERROR_INVALID_HANDLE, ERROR_INVALID_PARAMETER, or ERROR_INVALID_HANDLE_STATE

UINT WINAPI MsiViewGetColumnInfo(MSIHANDLE hView,
	MSICOLINFO eColumnInfo,        // retrieve columns names or definitions
	MSIHANDLE *phRecord);          // returned data record containing all names or definitions

// Release the result set for an executed view, to allow re-execution
// Only needs to be called if not all records have been fetched
// Returns ERROR_SUCCESS, ERROR_INVALID_HANDLE, ERROR_INVALID_HANDLE_STATE

UINT WINAPI MsiViewClose(MSIHANDLE hView);

// Return a record containing the names of all primary key columns for a given table
// Returns an MSIHANDLE for a record containing the name of each column.
// The field count of the record corresponds to the number of primary key columns.
// Field [0] of the record contains the table name.
// Returns ERROR_SUCCESS, ERROR_INVALID_HANDLE, ERROR_INVALID_TABLE

UINT WINAPI MsiDatabaseGetPrimaryKeysA(MSIHANDLE hDatabase,
	LPCSTR    szTableName,       // the name of a specific table <case-sensitive>
	MSIHANDLE  *phRecord);         // returned record if ERROR_SUCCESS
UINT WINAPI MsiDatabaseGetPrimaryKeysW(MSIHANDLE hDatabase,
	LPCWSTR    szTableName,       // the name of a specific table <case-sensitive>
	MSIHANDLE  *phRecord);         // returned record if ERROR_SUCCESS
#ifdef UNICODE
#define MsiDatabaseGetPrimaryKeys  MsiDatabaseGetPrimaryKeysW
#else
#define MsiDatabaseGetPrimaryKeys  MsiDatabaseGetPrimaryKeysA
#endif // !UNICODE

// Return an enum defining the state of the table (temporary, unknown, or persistent).
// Returns MSICONDITION_ERROR, MSICONDITION_FALSE, MSICONDITION_TRUE, MSICONDITION_NONE

MSICONDITION WINAPI MsiDatabaseIsTablePersistentA(MSIHANDLE hDatabase,
	LPCSTR szTableName);         // the name of a specific table
MSICONDITION WINAPI MsiDatabaseIsTablePersistentW(MSIHANDLE hDatabase,
	LPCWSTR szTableName);         // the name of a specific table
#ifdef UNICODE
#define MsiDatabaseIsTablePersistent  MsiDatabaseIsTablePersistentW
#else
#define MsiDatabaseIsTablePersistent  MsiDatabaseIsTablePersistentA
#endif // !UNICODE

// --------------------------------------------------------------------------
// Summary information stream management functions
// --------------------------------------------------------------------------

// Integer Property IDs:    1, 14, 15, 16, 19 
// DateTime Property IDs:   10, 11, 12, 13
// Text Property IDs:       2, 3, 4, 5, 6, 7, 8, 9, 18
// Unsupported Propery IDs: 0 (PID_DICTIONARY), 17 (PID_THUMBNAIL)

// Obtain a handle for the _SummaryInformation stream for an MSI database     

UINT WINAPI MsiGetSummaryInformationA(MSIHANDLE hDatabase, // 0 if not open
	LPCSTR  szDatabasePath,  // path to database, 0 if database handle supplied
	UINT     uiUpdateCount,    // maximium number of updated values, 0 to open read-only
	MSIHANDLE *phSummaryInfo); // returned handle to summary information data
UINT WINAPI MsiGetSummaryInformationW(MSIHANDLE hDatabase, // 0 if not open
	LPCWSTR  szDatabasePath,  // path to database, 0 if database handle supplied
	UINT     uiUpdateCount,    // maximium number of updated values, 0 to open read-only
	MSIHANDLE *phSummaryInfo); // returned handle to summary information data
#ifdef UNICODE
#define MsiGetSummaryInformation  MsiGetSummaryInformationW
#else
#define MsiGetSummaryInformation  MsiGetSummaryInformationA
#endif // !UNICODE

// Obtain the number of existing properties in the SummaryInformation stream

UINT WINAPI MsiSummaryInfoGetPropertyCount(MSIHANDLE hSummaryInfo,
	UINT *puiPropertyCount); // pointer to location to return total property count

// Set a single summary information property
// Returns ERROR_SUCCESS, ERROR_INVALID_HANDLE, ERROR_UNKNOWN_PROPERTY

UINT WINAPI MsiSummaryInfoSetPropertyA(MSIHANDLE hSummaryInfo,
	UINT     uiProperty,     // property ID, one of allowed values for summary information
	UINT     uiDataType,     // VT_I4, VT_LPSTR, VT_FILETIME, or VT_EMPTY