Funzione MsiEnumPatchesExA (msi.h)

Articolo
11/20/2024

La funzione msiEnumPatchesEx enumera tutte le patch in un contesto specifico o in tutti i contesti. Le patch già applicate ai prodotti vengono enumerate. Vengono enumerate anche le patch registrate ma non ancora applicate ai prodotti.

Sintassi

UINT MsiEnumPatchesExA(
  [in, optional]      LPCSTR            szProductCode,
  [in, optional]      LPCSTR            szUserSid,
  [in]                DWORD             dwContext,
  [in]                DWORD             dwFilter,
  [in]                DWORD             dwIndex,
  [out, optional]     CHAR [39]         szPatchCode,
  [out, optional]     CHAR [39]         szTargetProductCode,
  [out, optional]     MSIINSTALLCONTEXT *pdwTargetProductContext,
  [out, optional]     LPSTR             szTargetUserSid,
  [in, out, optional] LPDWORD           pcchTargetUserSid
);

Parametri

[in, optional] szProductCode

Stringa con terminazione Null che specifica il ProductCode GUID del prodotto le cui patch sono enumerate. Se nonnull, l'enumerazione patch è limitata alle istanze di questo prodotto nell'ambito dell'utente e del contesto specificato da szUserSid e dwContext. Se NULL, vengono enumerate le patch per tutti i prodotti nel contesto specificato.

[in, optional] szUserSid

Stringa con terminazione Null che specifica un SID (Security Identifier) che limita il contesto dell'enumerazione. La speciale stringa SID "S-1-1-0" (Everyone) specifica l'enumerazione in tutti gli utenti del sistema. Un valore SID diverso da "S-1-1-0" viene considerato un SID utente e limita l'enumerazione a tale utente. Durante l'enumerazione per un utente diverso dall'utente corrente, le patch applicate in un contesto non gestito per utente usando una versione minore di Windows Installer versione 3.0, non vengono enumerate. Questo parametro può essere impostato su NULL per specificare l'utente corrente.

Tipo SID	Significato
NULL	Specifica l'utente attualmente connesso.
SID utente	Enumerazione per un utente specifico nel sistema. Un esempio di SID utente è "S-1-3-64-2415071341-1358098788-3127455600-2561".
s-1-1-0	Enumerazione in tutti gli utenti del sistema.

Nota Non è possibile usare la speciale stringa SID "S-1-5-18" (System) per enumerare prodotti o patch installati come per computer. L'impostazione del valore SID su "S-1-5-18" restituisce ERROR_INVALID_PARAMETER. Quando dwContext è impostato solo su MSIINSTALLCONTEXT_MACHINE, szUserSid deve essere NULL.

[in] dwContext

Limita l'enumerazione a una o a una combinazione di contesti. Questo parametro può essere qualsiasi o una combinazione dei valori seguenti.

Contesto	Significato
MSIINSTALLCONTEXT_USERMANAGED	Enumerazione estesa a tutte le installazioni gestite dall'utente per gli utenti che szUserSid. Un SID non valido non restituisce elementi.
MSIINSTALLCONTEXT_USERUNMANAGED	In questo contesto, solo le patch installate con Windows Installer versione 3.0 vengono enumerate per gli utenti che non sono l'utente corrente. Per l'utente corrente, la funzione enumera tutte le patch installate e nuove. Un SID non valido per szUserSid non restituisce elementi.
MSIINSTALLCONTEXT_MACHINE	Enumerazione estesa a tutte le installazioni per computer. Quando dwContext è impostato solo su MSIINSTALLCONTEXT_MACHINE, il parametro szUserSid deve essere NULL.

[in] dwFilter

Filtro per l'enumerazione. Questo parametro può essere uno o una combinazione dei parametri seguenti.

Filtro	Significato
MSIPATCHSTATE_APPLIED 1	L'enumerazione include patch applicate. L'enumerazione non include patch sostituite o obsolete.
MSIPATCHSTATE_SUPERSEDED 2	L'enumerazione include patch contrassegnate come sostituite.
MSIPATCHSTATE_OBSOLETED 4	L'enumerazione include patch contrassegnate come obsolete.
MSIPATCHSTATE_REGISTERED 8	L'enumerazione include patch registrate ma non ancora applicate. La funzione msiSourceListAddSourceEx può registrare nuove patch. Nota le patch registrate per utenti diversi dall'utente corrente e applicate nel contesto non gestito per utente non vengono enumerate.
MSIPATCHSTATE_ALL 15	L'enumerazione include tutte le patch applicate, obsolete, sostituite e registrate.

[in] dwIndex

Indice della patch da recuperare. Questo parametro deve essere zero per la prima chiamata alla funzione MsiEnumPatchesEx e quindi incrementato per le chiamate successive. Il parametro dwIndex deve essere incrementato solo se la chiamata precedente ha restituito ERROR_SUCCESS.

[out, optional] szPatchCode

Buffer di output che contiene il GUID della patch da enumerare. Il buffer deve essere sufficientemente grande da contenere il GUID. Questo parametro può essere NULL.

[out, optional] szTargetProductCode

Buffer di output che contiene il ProductCode GUID del prodotto che riceve questa patch. Il buffer deve essere sufficientemente grande da contenere il GUID. Questo parametro può essere NULL.

[out, optional] pdwTargetProductContext

Restituisce il contesto della patch da enumerare. Il valore di output può essere MSIINSTALLCONTEXT_USERMANAGED, MSIINSTALLCONTEXT_USERUNMANAGEDo MSIINSTALLCONTEXT_MACHINE. Questo parametro può essere NULL.

[out, optional] szTargetUserSid

Buffer di output che riceve il SID stringa dell'account in cui esiste questa istanza di patch. Questo buffer restituisce una stringa vuota per un contesto per computer.

Questo buffer deve essere sufficientemente grande da contenere il SID. Se il buffer è troppo piccolo, la funzione restituisce ERROR_MORE_DATA e imposta *pcchTargetUserSid al numero di TCHAR nel valore, senza includere il carattere NULL di terminazione.

Se il szTargetUserSid è impostato su NULL e pcchTargetUserSid è impostato su un puntatore valido, la funzione restituisce ERROR_SUCCESS e imposta *pcchTargetUserSid sul numero di TCHAR nel valore, senza includere il carattere di terminazione NULL. La funzione può quindi essere chiamata di nuovo per recuperare il valore, con szTargetUserSid buffer sufficientemente grande da contenere *pcchTargetUserSid + 1 caratteri.

Se szTargetUserSid e pcchTargetUserSid sono entrambi impostati su NULL, la funzione restituisce ERROR_SUCCESS se il valore esiste, senza recuperare il valore.

[in, out, optional] pcchTargetUserSid

Puntatore a una variabile che specifica il numero di TCHAR nel buffer szTargetUserSid . Quando la funzione termina, questo parametro viene impostato sulle dimensioni del valore richiesto indipendentemente dal fatto che la funzione copia il valore nel buffer specificato. La dimensione viene restituita come numero di TCHAR nel valore richiesto, senza includere il carattere Null di terminazione.

Questo parametro può essere impostato su NULL solo se szTargetUserSid è null, altrimenti la funzione restituisce ERROR_INVALID_PARAMETER.

Valore restituito

La funzione msiEnumPatchesEx restituisce uno dei valori seguenti.

Codice restituito	Descrizione
ERROR_ACCESS_DENIED	La funzione non riesce ad accedere a una risorsa con privilegi insufficienti.
ERROR_BAD_CONFIGURATION	I dati di configurazione sono danneggiati.
ERROR_INVALID_PARAMETER	Alla funzione viene passato un parametro non valido.
ERROR_NO_MORE_ITEMS	Non sono presenti altre patch da enumerare.
ERROR_SUCCESS	La patch viene enumerata correttamente.
ERROR_UNKNOWN_PRODUCT	Il prodotto che szProduct non è installato nel computer nei contesti specificati.
ERROR_MORE_DATA	Questo valore viene restituito quando pcchTargetUserSid punta a una dimensione del buffer inferiore al necessario per copiare il SID. In questo caso, l'utente può correggere il buffer e chiamare di nuovo MsiEnumPatchesEx per lo stesso valore di indice.

Osservazioni

Gli utenti non amministratori possono enumerare le patch solo all'interno della loro visibilità. Gli amministratori possono enumerare le patch per altri contesti utente.

Nota

L'intestazione msi.h definisce MsiEnumPatchesEx come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows Installer 5.0 in Windows Server 2012, Windows 8, Windows Server 2008 R2 o Windows 7. Windows Installer 4.0 o Windows Installer 4.5 in Windows Server 2008 o Windows Vista. Per informazioni sul Service Pack minimo di Windows richiesto da una versione di Windows Installer, vedere Requisiti di windows Run-Time.
piattaforma di destinazione	Finestre
intestazione	msi.h
libreria	Msi.lib
dll	Msi.dll

Vedere anche

contesto di installazione

MsiSourceListAddSourceEx

non supportato in Windows Installer 2.0 e versioni precedenti

ProductCode

Condividi tramite