MsiEnumClientsExA, fonction (msi.h)

Article
08/24/2023

La fonction MsiEnumClientsEx énumère les applications installées qui utilisent un composant spécifié. La fonction récupère un code de produit pour une application chaque fois qu’elle est appelée.

Windows Installer 4.5 ou version antérieure : Non pris en charge. Cette fonction est disponible à partir de Windows Installer 5.0.

Syntaxe

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
);

Paramètres

[in] szComponent

GUID du code du composant qui identifie le composant. La fonction énumère les applications qui utilisent ce composant.

[in, optional] szUserSid

Valeur de chaîne terminée par null qui contient un identificateur de sécurité (SID). L’énumération des applications s’étend aux utilisateurs identifiés par ce SID. La chaîne SID spéciale s-1-1-0 (Tout le monde) énumère toutes les applications pour tous les utilisateurs du système. Une valeur SID autre que s-1-1-0 spécifie un SID utilisateur pour un utilisateur particulier et énumère les instances d’applications installées par l’utilisateur spécifié.

Type SID	Signification
NULL	Spécifie l’utilisateur actuellement connecté.
SID de l’utilisateur	Spécifie une énumération pour un utilisateur particulier. Un exemple de SID utilisateur est « S-1-3-64-2415071341-1358098788-3127455600-2561 ».
s-1-1-0	Spécifie une énumération pour tous les utilisateurs du système.

Note La chaîne SID spéciale s-1-5-18 (Système) ne peut pas être utilisée pour énumérer les applications qui existent dans le contexte d’installation par ordinateur. La définition de la valeur sid sur s-1-5-18 renvoie ERROR_INVALID_PARAMETER. Lorsque dwContext est défini sur MSIINSTALLCONTEXT_MACHINE uniquement, la valeur de szUserSid doit être NULL.

[in] dwContext

Indicateur qui étend l’énumération aux instances d’applications installées dans le contexte d’installation spécifié. L’énumération inclut uniquement les instances d’applications installées par les utilisateurs identifiés par szUserSid.

Il peut s’agir d’une combinaison des valeurs suivantes.

Context	Signification
MSIINSTALLCONTEXT_USERMANAGED 1	Inclure les applications installées dans le contexte d’installation gérée par utilisateur.
MSIINSTALLCONTEXT_USERUNMANAGED 2	Incluez les applications installées dans le contexte d’installation non managée par utilisateur.
MSIINSTALLCONTEXT_MACHINE 4	Inclure les applications installées dans le contexte d’installation par ordinateur. Lorsque dwInstallContext est défini sur MSIINSTALLCONTEXT_MACHINE uniquement, la valeur du paramètre szUserSID doit être NULL.

[in] dwProductIndex

Spécifie l’index de l’application à récupérer. La valeur de ce paramètre doit être égale à zéro (0) dans le premier appel à la fonction. Pour chaque appel suivant, l’index doit être incrémenté de 1. L’index ne doit être incrémenté que si l’appel précédent à la fonction retourne ERROR_SUCCESS.

[out, optional] szProductBuf

Valeur de chaîne qui reçoit le code de produit pour l’application. La longueur de la mémoire tampon à cet emplacement doit être suffisamment grande pour contenir une valeur de chaîne terminée par null contenant le code de produit. Les 38 premiers caractères TCHAR reçoivent le GUID du composant, et le 39e caractère reçoit un caractère NULL de fin.

[out, optional] pdwInstalledContext

Indicateur qui donne le contexte d’installation de l’application.

Il peut s’agir d’une combinaison des valeurs suivantes.

Context	Signification
MSIINSTALLCONTEXT_USERMANAGED 1	L’application est installée dans le contexte d’installation gérée par utilisateur.
MSIINSTALLCONTEXT_USERUNMANAGED 2	L’application est installée dans le contexte d’installation non managée par utilisateur.
MSIINSTALLCONTEXT_MACHINE 4	L’application se trouve dans le contexte d’installation par ordinateur.

[out, optional] szSid

Reçoit l’identificateur de sécurité (SID) qui identifie l’utilisateur qui a installé l’application. L’emplacement reçoit une valeur de chaîne vide si cette instance de l’application existe dans un contexte d’installation par ordinateur.

La longueur de la mémoire tampon doit être suffisamment grande pour contenir une valeur de chaîne terminée par null contenant le SID. Si la mémoire tampon est trop petite, la fonction retourne ERROR_MORE_DATA et l’emplacement pointé par pcchSid reçoit le nombre de TCHAR dans le SID, sans inclure le caractère NULL de fin.

Si szSid a la valeur NULL et que pcchSid est un pointeur valide vers un emplacement en mémoire, la fonction retourne ERROR_SUCCESS et l’emplacement reçoit le nombre de TCHAR dans le SID, sans inclure le caractère null de fin. La fonction peut ensuite être appelée à nouveau pour récupérer la valeur, avec la mémoire tampon szSid redimensionnée suffisamment grande pour contenir *pcchSid + 1 caractères.

Type SID	Signification
Chaîne vide	L’application est installée dans un contexte d’installation par ordinateur.
SID de l’utilisateur	SID de l’utilisateur qui a installé le produit.

[in, out, optional] pcchSid

Pointeur vers un emplacement en mémoire qui contient une variable qui spécifie le nombre de TCHAR dans le SID, sans inclure le caractère null de fin. Lorsque la fonction retourne, cette variable est définie sur la taille du SID demandé, que la fonction puisse ou non copier correctement le SID et le caractère null de fin dans l’emplacement de mémoire tampon vers lequel szSid pointe. La taille est retournée en tant que nombre de TCHAR dans la valeur demandée, sans inclure le caractère null de fin.

Ce paramètre peut être défini sur NULL uniquement si szSid a également la valeur NULL, sinon la fonction retourne ERROR_INVALID_PARAMETER. Si szSid et pcchSid sont tous deux définis sur NULL, la fonction retourne ERROR_SUCCESS si le SID existe, sans récupérer la valeur du SID.

Valeur retournée

La fonction MsiEnumClientsEx retourne l’une des valeurs suivantes.

Code de retour	Description
ERROR_ACCESS_DENIED	Les privilèges d’administrateur sont requis pour énumérer les composants des applications installées par des utilisateurs autres que l’utilisateur actuel.
ERROR_BAD_CONFIGURATION	Les données de configuration sont endommagées.
ERROR_INVALID_PARAMETER	Un paramètre non valide est passé à la fonction .
ERROR_NO_MORE_ITEMS	Il n’y a plus d’applications à énumérer.
ERROR_SUCCESS	La fonction a réussi.
ERROR_MORE_DATA	La mémoire tampon fournie était trop petite pour contenir la valeur entière.
ERROR_FUNCTION_FAILED	Échec de la fonction.

Notes

L’en-tête msi.h définit MsiEnumClientsEx en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Spécifications


Client minimal pris en charge	Windows Installer 5.0 sur Windows Server 2012, Windows 8, Windows Server 2008 R2 ou Windows 7. Pour plus d’informations sur le Service Pack Windows minimal requis par une version de Windows Installer, consultez Configuration requise pour le runtime Windows Installer.
Plateforme cible	Windows
En-tête	msi.h
Bibliothèque	Msi.lib
DLL	Msi.dll