Funzione MsiEnumClientsExA (msi.h)

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 chiamata.

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 stringa SID speciale s-1-1-0 (Tutti) 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 utente specifico ed enumera le istanze di applicazioni installate dall'utente specificato.

Tipo SID Significato
NULL
Specifica l'utente attualmente connesso.
SID utente
Specifica un'enumerazione per un utente specifico. Un esempio di SID utente è "S-1-3-64-2415071341-1358098788-312745600-2561".
s-1-1-0
Specifica un'enumerazione per tutti gli utenti del sistema.
 
Nota Impossibile usare la stringa SID speciale s-1-5-18 (System) per enumerare le applicazioni esistenti 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 di applicazioni installate nel contesto di installazione specificato. L'enumerazione include solo istanze di applicazioni installate dagli utenti identificati da szUserSid.

Questa può essere 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 applicazioni installate nel contesto di installazione per utente-non gestito.
MSIINSTALLCONTEXT_MACHINE
4
Includere 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 sufficiente per 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 terminante.

[out, optional] pdwInstalledContext

Flag che fornisce il contesto di installazione dell'applicazione.

Questa può essere 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 non gestita per utente.
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 abbastanza grande per contenere un valore stringa con terminazione null contenente il SID. Se il buffer è troppo piccolo, la funzione restituisce ERROR_MORE_DATA e la posizione puntata da pcchSid riceve il numero di TCHAR nel SID, non incluso il carattere NULL terminante.

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, non incluso il carattere null terminante. La funzione può quindi essere chiamata di nuovo per recuperare il valore, con il buffer szSid 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, non incluso il carattere Null terminante. Quando la funzione restituisce, questa variabile viene impostata sulle dimensioni del SID richiesto se la funzione può 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, non incluso il carattere Null terminante.

Questo parametro può essere impostato su NULL solo se szSid è 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 installati dagli utenti diversi dall'utente corrente.
ERROR_BAD_CONFIGURATION
I dati di configurazione sono danneggiati.
ERROR_INVALID_PARAMETER
Un parametro non valido viene passato alla funzione.
ERROR_NO_MORE_ITEMS
Non sono presenti più applicazioni da enumerare.
ERROR_SUCCESS
Funzione completata.
ERROR_MORE_DATA
Il buffer fornito era troppo piccolo per contenere l'intero valore.
ERROR_FUNCTION_FAILED
La funzione non è riuscita.

Commenti

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 preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti

   
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 i requisiti di Windows Installer Run-Time.
Piattaforma di destinazione Windows
Intestazione msi.h
Libreria Msi.lib
DLL Msi.dll