Funzione MsiEnumClientsExA (msi.h)

Articolo
11/20/2024

La funzione msiEnumClientsEx enumera le applicazioni installate che usano un componente specificato. La funzione recupera un codice prodotto per un'applicazione ogni volta che viene chiamato.

Windows Installer 4.5 o versioni precedenti: Non supportato. Questa funzione è disponibile a partire da Windows Installer 5.0.

Sintassi

UINT MsiEnumClientsExA(
  [in]                LPCSTR            szComponent,
  [in, optional]      LPCSTR            szUserSid,
  [in]                DWORD             dwContext,
  [in]                DWORD             dwProductIndex,
  [out, optional]     CHAR [39]         szProductBuf,
  [out, optional]     MSIINSTALLCONTEXT *pdwInstalledContext,
  [out, optional]     LPSTR             szSid,
  [in, out, optional] LPDWORD           pcchSid
);

Parametri

[in] szComponent

GUID del codice del componente che identifica il componente. La funzione enumera le applicazioni che usano questo componente.

[in, optional] szUserSid

Valore stringa con terminazione Null contenente un identificatore di sicurezza (SID). L'enumerazione delle applicazioni si estende agli utenti identificati da questo SID. La speciale stringa SID s-1-1-0 (Everyone) enumera tutte le applicazioni per tutti gli utenti del sistema. Un valore SID diverso da s-1-1-0 specifica un SID utente per un determinato utente ed enumera le istanze delle applicazioni installate dall'utente specificato.

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

Nota Non è possibile usare la speciale stringa SID s-1-5-18 (System) per enumerare le applicazioni presenti nel contesto di installazione per computer. L'impostazione del valore SID su s-1-5-18 restituisce ERROR_INVALID_PARAMETER. Quando dwContext è impostato solo su MSIINSTALLCONTEXT_MACHINE, il valore di szUserSid deve essere NULL.

[in] dwContext

Flag che estende l'enumerazione alle istanze delle applicazioni installate nel contesto di installazione specificato. L'enumerazione include solo le istanze di applicazioni installate dagli utenti identificati da szUserSid.

Può trattarsi di una combinazione dei valori seguenti.

Contesto	Significato
MSIINSTALLCONTEXT_USERMANAGED 1	Includere le applicazioni installate nel contesto di installazione gestita dall'utente.
MSIINSTALLCONTEXT_USERUNMANAGED 2	Includere le applicazioni installate nel contesto di installazione per utente non gestito.
MSIINSTALLCONTEXT_MACHINE 4	Includere le applicazioni installate nel contesto di installazione per computer. Quando dwInstallContext è impostato solo su MSIINSTALLCONTEXT_MACHINE, il valore del parametro szUserSID deve essere NULL.

[in] dwProductIndex

Specifica l'indice dell'applicazione da recuperare. Il valore di questo parametro deve essere zero (0) nella prima chiamata alla funzione. Per ogni chiamata successiva, l'indice deve essere incrementato di 1. L'indice deve essere incrementato solo se la chiamata precedente alla funzione restituisce ERROR_SUCCESS.

[out, optional] szProductBuf

Valore stringa che riceve il codice prodotto per l'applicazione. La lunghezza del buffer in questa posizione deve essere sufficientemente grande da contenere un valore stringa con terminazione Null contenente il codice prodotto. I primi 38 caratteri TCHAR ricevono il GUID per il componente e il 39° carattere riceve un carattere NULL di terminazione.

[out, optional] pdwInstalledContext

Flag che fornisce il contesto di installazione dell'applicazione.

Può trattarsi di una combinazione dei valori seguenti.

Contesto	Significato
MSIINSTALLCONTEXT_USERMANAGED 1	L'applicazione viene installata nel contesto di installazione gestita dall'utente.
MSIINSTALLCONTEXT_USERUNMANAGED 2	L'applicazione viene installata nel contesto di installazione per utente non gestito.
MSIINSTALLCONTEXT_MACHINE 4	L'applicazione si trova nel contesto di installazione per computer.

[out, optional] szSid

Riceve l'identificatore di sicurezza (SID) che identifica l'utente che ha installato l'applicazione. Il percorso riceve un valore stringa vuoto se questa istanza dell'applicazione esiste in un contesto di installazione per computer.

La lunghezza del buffer deve essere sufficientemente grande da contenere un valore stringa con terminazione Null contenente il SID. Se il buffer è troppo piccolo, la funzione restituisce ERROR_MORE_DATA e la posizione a cui punta pcchSid riceve il numero di TCHAR nel SID, senza includere il carattere NULL di terminazione.

Se szSid è impostato su NULL e pcchSid è un puntatore valido a una posizione in memoria, la funzione restituisce ERROR_SUCCESS e la posizione riceve il numero di TCHAR nel SID, senza includere il carattere Null di terminazione. La funzione può quindi essere chiamata di nuovo per recuperare il valore, con il szSid buffer ridimensionato abbastanza grande per contenere *pcchSid + 1 caratteri.

Tipo SID	Significato
Stringa vuota	L'applicazione viene installata in un contesto di installazione per computer.
SID utente	SID per l'utente che ha installato il prodotto.

[in, out, optional] pcchSid

Puntatore a una posizione in memoria contenente una variabile che specifica il numero di TCHAR nel SID, senza includere il carattere Null di terminazione. Quando la funzione termina, questa variabile viene impostata sulle dimensioni del SID richiesto indipendentemente dal fatto che la funzione possa copiare correttamente il SID e terminare il carattere Null nella posizione del buffer a cui punta szSid. 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 null, altrimenti la funzione restituisce ERROR_INVALID_PARAMETER. Se szSid e pcchSid sono entrambi impostati su NULL , la funzione restituisce ERROR_SUCCESS se il SID esiste, senza recuperare il valore SID.

Valore restituito

La funzione msiEnumClientsEx restituisce uno dei valori seguenti.

Codice restituito	Descrizione
ERROR_ACCESS_DENIED	I privilegi di amministratore sono necessari per enumerare i componenti delle applicazioni installate dagli utenti diversi dall'utente corrente.
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 applicazioni da enumerare.
ERROR_SUCCESS	La funzione ha avuto esito positivo.
ERROR_MORE_DATA	Il buffer fornito era troppo piccolo per contenere l'intero valore.
ERROR_FUNCTION_FAILED	La funzione non è riuscita.

Osservazioni

Nota

L'intestazione msi.h definisce MsiEnumClientsEx 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. 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

Condividi tramite